# AchieveApex REST API reference

> Complete reference of the AchieveApex public REST API in one file, for developers and AI assistants.
> Base URL: https://integrations.achieveapex.com · Auth: header `x-api-key: YOUR_API_KEY` (one key per organization).
> Web version: https://www.achieveapex.com/docs/api-reference/authentication · OpenAPI 3.1: https://www.achieveapex.com/docs/openapi.json · Generated: 2026-11-21

Rules an AI assistant must follow with this API:
- Use only endpoints and fields documented below. Do not invent parameters.
- GET requests take filters, sorting and pagination in the query string (`$limit` max 50, `$skip`, `$sort[field]=-1`), never in a JSON body.
- POST/PATCH send JSON with `Content-Type: application/json`. DELETE is a soft delete.
- Custom actions are `POST /<resource>` with header `X-Service-Method: <action>`.

## Contents

- [Authentication](#authentication)
- [Requests, filtering and pagination](#requests)
- [Errors and rate limits](#errors)
- [Use with AI and LLMs](#ai-and-llms)
- Activities: [Overview](#activities) · [List activities](#activities--list) · [Get an activity](#activities--get) · [Create an activity](#activities--create) · [Update an activity](#activities--update) · [Delete an activity](#activities--delete) · [Activities errors](#activities--errors)
- Activity types: [Overview](#activity-types) · [List activity types](#activity-types--list) · [Get an activity type](#activity-types--get) · [Create an activity type](#activity-types--create) · [Update an activity type](#activity-types--update) · [Delete an activity type](#activity-types--delete) · [Activity types errors](#activity-types--errors)
- AI Assistant Skills: [Overview](#ai-assistant-skills) · [List skills](#ai-assistant-skills--list) · [Get a skill](#ai-assistant-skills--get) · [Create a skill](#ai-assistant-skills--create) · [Update a skill](#ai-assistant-skills--update) · [Delete a skill](#ai-assistant-skills--delete)
- AI Assistants: [Overview](#ai-assistants) · [List AI assistants](#ai-assistants--list) · [Get an AI assistant](#ai-assistants--get) · [Create an AI assistant](#ai-assistants--create) · [Update an AI assistant](#ai-assistants--update) · [Delete an AI assistant](#ai-assistants--delete) · [Configure a voice assistant](#ai-assistants--voice) · [Get a history entry](#ai-assistants--history-get) · [List configuration history](#ai-assistants--history) · [List transcription languages](#ai-assistants--voice-transcription-languages) · [List voice LLM models](#ai-assistants--voice-models) · [List voices](#ai-assistants--voice-voices) · [Restore a configuration version](#ai-assistants--restore)
- AI Models: [Overview](#ai-models) · [List AI models](#ai-models--list) · [Get an AI model](#ai-models--get)
- API Tools: [Overview](#api-tools) · [List API tools](#api-tools--list) · [Get an API tool](#api-tools--get) · [Create an API tool](#api-tools--create) · [Update an API tool](#api-tools--update) · [Delete an API tool](#api-tools--delete)
- Automation executions: [Overview](#automations-executions) · [List executions](#automations-executions--list) · [Get an execution](#automations-executions--get) · [Run an automation](#automations-executions--create)
- Campaign Segments: [Overview](#campaign-segments) · [List segments](#campaign-segments--list) · [Get a segment](#campaign-segments--get) · [Update a segment](#campaign-segments--update) · [Delete a segment](#campaign-segments--delete) · [Export campaign segment contacts](#campaign-segments--export-contacts) · [Get segment fields](#campaign-segments--schema-builder) · [Preview the contacts of a segment](#campaign-segments--run-query)
- Companies: [Overview](#companies) · [List companies](#companies--list) · [Get a company](#companies--get) · [Create a company](#companies--create) · [Update a company](#companies--update) · [Delete a company](#companies--delete) · [Companies errors](#companies--errors) · [Search companies](#companies--search)
- Contacts: [Overview](#contacts) · [List contacts](#contacts--list) · [Get a contact](#contacts--get) · [Create a contact](#contacts--create) · [Update a contact](#contacts--update) · [Delete a contact](#contacts--delete) · [Contacts errors](#contacts--errors) · [Search contacts](#contacts--search)
- Conversation files: [Overview](#conversation-files) · [List files](#conversation-files--list) · [Get a file](#conversation-files--get) · [Upload a file](#conversation-files--upload)
- Conversation messages: [Overview](#conversation-messages) · [List messages](#conversation-messages--list) · [Get a message](#conversation-messages--get) · [Edit a note](#conversation-messages--update) · [Delete a message](#conversation-messages--delete) · [Send a message](#conversation-messages--send) · [Send a WhatsApp template](#conversation-messages--send-whatsapp-template)
- Conversations: [Overview](#conversations) · [List conversations](#conversations--list) · [Get a conversation](#conversations--get) · [Create a conversation](#conversations--create) · [Update a conversation](#conversations--patch) · [Delete a conversation](#conversations--delete) · [Get a bulk action](#conversations--bulk-actions-get) · [List bulk actions](#conversations--bulk-actions-list) · [Run a bulk action on conversations](#conversations--bulk-actions) · [Start a WhatsApp conversation](#conversations--initiate-whatsapp)
- Custom fields: [Overview](#custom-fields) · [List custom fields](#custom-fields--list) · [Get a custom field](#custom-fields--get) · [Create a custom field](#custom-fields--create) · [Update a custom field](#custom-fields--update) · [Delete a custom field](#custom-fields--delete)
- Deal products: [Overview](#deal-products) · [List deal products](#deal-products--list) · [Get a deal product](#deal-products--get) · [Add a product to a deal](#deal-products--create) · [Update a deal product](#deal-products--update) · [Remove a product from a deal](#deal-products--delete) · [Deal products errors](#deal-products--errors)
- Deals: [Overview](#deals) · [List deals](#deals--list) · [Get a deal](#deals--get) · [Create a deal](#deals--create) · [Update a deal](#deals--update) · [Delete a deal](#deals--delete) · [Deals errors](#deals--errors)
- Export data: [Overview](#export-data) · [Export data](#export-data--create)
- Loyalty actions: [Overview](#loyalty-actions) · [Get wallet links](#loyalty-actions--wallet-links) · [Load gift card balance](#loyalty-actions--load-balance) · [Register a purchase](#loyalty-actions--register-purchase) · [Scan a code](#loyalty-actions--scan) · [Send the card link](#loyalty-actions--send-card) · [Use a membership](#loyalty-actions--use-membership)
- Loyalty members: [Overview](#loyalty-members) · [List or look up loyalty members](#loyalty-members--list) · [Get a loyalty member](#loyalty-members--get) · [Enroll a loyalty member](#loyalty-members--create) · [Update a loyalty member](#loyalty-members--update) · [Delete a loyalty member](#loyalty-members--delete)
- Loyalty programs: [Overview](#loyalty-programs) · [List loyalty programs](#loyalty-programs--list) · [Get a loyalty program](#loyalty-programs--get) · [Create a loyalty program](#loyalty-programs--create) · [Update a loyalty program](#loyalty-programs--update) · [Delete a loyalty program](#loyalty-programs--delete)
- Loyalty redemptions: [Overview](#loyalty-redemptions) · [List loyalty redemptions](#loyalty-redemptions--list) · [Get a loyalty redemption](#loyalty-redemptions--get) · [Redeem a reward](#loyalty-redemptions--create) · [Use or cancel a redemption](#loyalty-redemptions--update)
- Loyalty reports: [Overview](#loyalty-reports)
- Loyalty rewards: [Overview](#loyalty-rewards) · [List loyalty rewards](#loyalty-rewards--list) · [Get a loyalty reward](#loyalty-rewards--get) · [Create a loyalty reward](#loyalty-rewards--create) · [Update a loyalty reward](#loyalty-rewards--update) · [Delete a loyalty reward](#loyalty-rewards--delete)
- Loyalty tiers: [Overview](#loyalty-tiers) · [List loyalty tiers](#loyalty-tiers--list) · [Get a loyalty tier](#loyalty-tiers--get) · [Create a loyalty tier](#loyalty-tiers--create) · [Update a loyalty tier](#loyalty-tiers--update) · [Delete a loyalty tier](#loyalty-tiers--delete)
- Loyalty transactions: [Overview](#loyalty-transactions) · [List loyalty transactions](#loyalty-transactions--list) · [Get a loyalty transaction](#loyalty-transactions--get) · [Adjust a balance](#loyalty-transactions--create)
- MCP Tool Connections: [Overview](#mcp-tool-connections) · [Test an MCP connection](#mcp-tool-connections--test)
- Organization invitations: [Overview](#organizations-users-invites) · [List invitations](#organizations-users-invites--list) · [Get an invitation](#organizations-users-invites--get) · [Create an invitation](#organizations-users-invites--create) · [Update an invitation](#organizations-users-invites--update) · [Cancel an invitation](#organizations-users-invites--delete)
- Organizations: [Overview](#organizations) · [List organizations](#organizations--list) · [Get an organization](#organizations--get) · [Update an organization](#organizations--update) · [Organizations errors](#organizations--errors)
- Pipeline stages: [Overview](#pipeline-stages) · [List pipeline stages](#pipeline-stages--list) · [Get a pipeline stage](#pipeline-stages--get) · [Create a pipeline stage](#pipeline-stages--create) · [Update a pipeline stage](#pipeline-stages--update) · [Delete a pipeline stage](#pipeline-stages--delete)
- Pipelines: [Overview](#pipelines) · [List pipelines](#pipelines--list) · [Get a pipeline](#pipelines--get) · [Create a pipeline](#pipelines--create) · [Update a pipeline](#pipelines--update) · [Delete a pipeline](#pipelines--delete)
- Predefined messages: [Overview](#conversation-predefined-messages) · [List predefined messages](#conversation-predefined-messages--list) · [Get a predefined message](#conversation-predefined-messages--get) · [Create a predefined message](#conversation-predefined-messages--create) · [Update a predefined message](#conversation-predefined-messages--update) · [Delete a predefined message](#conversation-predefined-messages--delete)
- Product categories: [Overview](#product-categories) · [List product categories](#product-categories--list) · [Get a product category](#product-categories--get) · [Create a product category](#product-categories--create) · [Update a product category](#product-categories--update) · [Delete a product category](#product-categories--delete) · [Error Handling](#product-categories--errors)
- Product media: [Overview](#product-media) · [List product media](#product-media--list) · [Get a product media item](#product-media--get) · [Upload product media](#product-media--create) · [Update product media](#product-media--update) · [Delete product media](#product-media--delete) · [Error Handling](#product-media--errors)
- Products: [Overview](#products) · [List products](#products--list) · [Get a product](#products--get) · [Create a product](#products--create) · [Update a product](#products--update) · [Delete a product](#products--delete) · [Error Handling](#products--errors)
- Reservation available slots: [Overview](#reservation-available-slots) · [Get available slots](#reservation-available-slots--list)
- Reservation booking links: [Overview](#reservation-booking-links) · [List reservation booking links](#reservation-booking-links--list) · [Get a reservation booking link](#reservation-booking-links--get) · [Create a reservation booking link](#reservation-booking-links--create) · [Update a reservation booking link](#reservation-booking-links--update) · [Delete a reservation booking link](#reservation-booking-links--delete)
- Reservation resource availability: [Overview](#reservation-resource-availability) · [List reservation resource availability](#reservation-resource-availability--list) · [Get a reservation resource availability block](#reservation-resource-availability--get) · [Create a reservation resource availability block](#reservation-resource-availability--create) · [Update a reservation resource availability block](#reservation-resource-availability--update) · [Delete a reservation resource availability block](#reservation-resource-availability--delete)
- Reservation resource exceptions: [Overview](#reservation-resource-exceptions) · [List reservation resource exceptions](#reservation-resource-exceptions--list) · [Get a reservation resource exception](#reservation-resource-exceptions--get) · [Create a reservation resource exception](#reservation-resource-exceptions--create) · [Update a reservation resource exception](#reservation-resource-exceptions--update) · [Delete a reservation resource exception](#reservation-resource-exceptions--delete)
- Reservation resources: [Overview](#reservation-resources) · [List reservation resources](#reservation-resources--list) · [Get a reservation resource](#reservation-resources--get) · [Create a reservation resource](#reservation-resources--create) · [Update a reservation resource](#reservation-resources--update) · [Delete a reservation resource](#reservation-resources--delete)
- Reservation service resources: [Overview](#reservation-service-resources) · [List reservation service resources](#reservation-service-resources--list) · [Get a reservation service resource](#reservation-service-resources--get) · [Create a reservation service resource](#reservation-service-resources--create) · [Update a reservation service resource](#reservation-service-resources--update) · [Delete a reservation service resource](#reservation-service-resources--delete)
- Reservation services: [Overview](#reservation-services) · [List reservation services](#reservation-services--list) · [Get a reservation service](#reservation-services--get) · [Create a reservation service](#reservation-services--create) · [Update a reservation service](#reservation-services--update) · [Delete a reservation service](#reservation-services--delete)
- Reservations: [Overview](#reservations) · [List reservations](#reservations--list) · [Get a reservation](#reservations--get) · [Create a reservation](#reservations--create) · [Update a reservation](#reservations--update) · [Delete a reservation](#reservations--delete)
- Support Tickets: [Overview](#support-tickets) · [List support tickets](#support-tickets--list) · [Get a support ticket](#support-tickets--get) · [Create a support ticket](#support-tickets--create) · [Update a support ticket](#support-tickets--update) · [Delete a support ticket](#support-tickets--delete) · [Support ticket errors](#support-tickets--errors)
- Upload URLs: [Overview](#s3-url-signing) · [Create an upload URL](#s3-url-signing--create)
- WhatsApp numbers: [Overview](#whatsapp-channels) · [List WhatsApp numbers](#whatsapp-channels--list) · [Get a WhatsApp number](#whatsapp-channels--get)
- WhatsApp templates: [Overview](#whatsapp-channel-message-templates) · [List WhatsApp templates](#whatsapp-channel-message-templates--list) · [Get a WhatsApp template](#whatsapp-channel-message-templates--get)

<a id="authentication"></a>

## Authentication

Source: https://www.achieveapex.com/docs/api-reference/authentication

The AchieveApex REST API lets you read and write the data of your organization: contacts, companies, deals, conversations, support tickets, products, reservations, loyalty, AI assistants and more. Every request is authenticated with an organization API key sent in the `x-api-key` header.

> **Using an AI assistant?** Download the whole reference as one file or point ChatGPT/Claude to it. See [Use with AI and LLMs](#ai-and-llms).

### Base URL

```
https://integrations.achieveapex.com
```

All paths in this reference are relative to the base URL: `/contacts` means `https://integrations.achieveapex.com/contacts`. The API only accepts HTTPS. Requests and responses are JSON (`Content-Type: application/json`).

### Create an API key

1. In AchieveApex, go to **Settings → Developers → API Keys**.
2. Create a key and copy it. Each key belongs to **one organization** and to the user who created it.
3. Store it in a secret manager or an environment variable. You can deactivate a key and create a new one at any time.

> **Important:** an API key gives full access to all the data of its organization. Never put it in browser code, mobile apps or public repositories.

### Send the key on every request

There is no login step. Add the header to every call:

```
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

```bash
curl -G https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode '$limit=5'
```

```bash
curl -X POST https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "organization_id": 101
  }'
```

### Organization scope

- An API key only works inside the organization it was created in. Reads are filtered to that organization automatically, even if the user who created the key belongs to other organizations or is an AchieveApex admin.
- Sending another organization's `organization_id` (in the body or as a filter) returns `403 Forbidden`.
- Most resources require `organization_id` in the body of `POST` requests: use your organization's ID (`GET /organizations` returns it).
- The key keeps the role its user has in that organization (owner, admin or member), so owner/admin-only actions need a key created by an owner or admin.
- Changing `organization_id` on an existing record is not allowed.

### Authentication errors

| Status | When | Example body |
|---|---|---|
| `401 Unauthorized` | The key does not exist or is inactive. | `{"name":"NotAuthenticated","message":"Invalid API key","code":401,"className":"not-authenticated"}` |
| `403 Forbidden` | No `x-api-key` header was sent (anonymous request), or the resource is not available to API keys. | `{"name":"Forbidden","message":"Access denied: You do not have permission to view contacts. ...","code":403,"className":"forbidden"}` |
| `429 Too Many Requests` | The organization exceeded its rate limit. | See [Errors and rate limits](#errors). |

### Next steps

- [Requests, filtering and pagination](#requests): how to list, filter, sort and page through any resource.
- [Errors and rate limits](#errors)
- [Use with AI and LLMs](#ai-and-llms): one-file download, OpenAPI spec and prompts.
- Start with a resource, for example [Contacts](#contacts).

---

<a id="requests"></a>

## Requests, filtering and pagination

Source: https://www.achieveapex.com/docs/api-reference/requests

Every resource in the API follows the same REST conventions, so once you know them for one resource you know them for all.

### Methods

| Operation | HTTP | Path | Body |
|---|---|---|---|
| List | `GET` | `/<resource>` | none, use the query string |
| Get one | `GET` | `/<resource>/:id` | none |
| Create | `POST` | `/<resource>` | JSON object |
| Update (partial) | `PATCH` | `/<resource>/:id` | JSON with only the fields to change |
| Delete | `DELETE` | `/<resource>/:id` | none |
| Custom action | `POST` | `/<resource>` + header `X-Service-Method: <action>` | JSON for the action |

`DELETE` is a **soft delete**: the record gets a `deleted_at` timestamp and stops appearing in list and get responses.

### Query string, never a body, on GET

`GET` requests ignore any JSON body. Filters, sorting and pagination go in the query string. With curl, `-G` plus `--data-urlencode` builds it for you:

```bash
curl -G https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'email=jane@example.com' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$sort[created_at]=-1'
```

curl turns that into this URL:

```
https://integrations.achieveapex.com/contacts?email=jane%40example.com&$limit=25&$sort[created_at]=-1
```

### Pagination

List endpoints return a page object:

```json
{
  "total": 132,
  "limit": 25,
  "skip": 0,
  "data": [ { "id": 1 }, { "id": 2 } ]
}
```

| Parameter | Description |
|---|---|
| `$limit` | Page size. Default `10`, maximum `50`. |
| `$skip` | Number of records to skip. Next page: `$skip = skip + limit` while `skip + limit < total`. |

### Filtering

Filter by any field of the resource with `field=value`. Operators:

| Operator | Example | Meaning |
|---|---|---|
| equality | `status=open` | equals |
| `$ne` | `status[$ne]=closed` | not equal |
| `$in` / `$nin` | `id[$in][]=1&id[$in][]=2` | in / not in a list |
| `$gt` `$gte` `$lt` `$lte` | `created_at[$gte]=2026-01-01T00:00:00Z` | comparisons (numbers, dates) |
| `$or` | `$or[0][email]=a@x.com&$or[1][phone]=5551234` | any of the conditions |

### Sorting and selecting fields

| Parameter | Example | Description |
|---|---|---|
| `$sort[field]` | `$sort[created_at]=-1` | `1` ascending, `-1` descending. Several allowed. |
| `$select[]` | `$select[]=id&$select[]=email` | Return only these fields. |

Unknown query parameters are rejected with `400 Bad Request`. Text search and extra flags (for example `searchTerm` or `fastJoinForContactList=true` on contacts) exist only where a resource's **List** page documents them.

### Dates, IDs and money

- Dates are ISO 8601 strings in UTC, for example `2026-11-11T15:04:05.000Z`.
- IDs are integers unless a page says otherwise.
- Monetary amounts are numbers in the record's currency; see the currency fields of each resource.

### Custom fields

CRM resources (contacts, companies, deals, support tickets, reservations) return `custom_fields_by_name` and `custom_fields_by_key`. To set custom fields, send `custom_fields_by_key` (an object of field key to value) in `POST`/`PATCH`; set a value to `null` to clear it. `custom_fields_by_name` is read-only and is rebuilt from the keys. Discover the available fields with [Custom fields](#custom-fields).

---

<a id="errors"></a>

## Errors and rate limits

Source: https://www.achieveapex.com/docs/api-reference/errors

The API uses standard HTTP status codes. Every error response has the same JSON shape.

### Error format

```json
{
  "name": "BadRequest",
  "message": "validation failed",
  "code": 400,
  "className": "bad-request",
  "data": [
    { "instancePath": "/email", "message": "must match format \"email\"" }
  ]
}
```

| Field | Description |
|---|---|
| `name` | Error type, for example `BadRequest`, `NotFound`. |
| `message` | Human-readable explanation. |
| `code` | HTTP status code. |
| `className` | Kebab-case version of `name`. |
| `data` | Optional details: validation errors, rate-limit counters, conflicting records. |

### Status codes

| Status | Name | Meaning |
|---|---|---|
| `200` | OK | Success. |
| `201` | Created | Record created (`POST`). |
| `400` | `BadRequest` | Invalid body or query string (unknown parameter, wrong type, missing required field). Check `data`. |
| `401` | `NotAuthenticated` | Invalid or inactive API key. |
| `403` | `Forbidden` | No API key sent, or the key cannot perform this action on this resource. |
| `404` | `NotFound` | The record does not exist, was deleted, or belongs to another organization. |
| `409` | `Conflict` | The change conflicts with existing data. |
| `429` | `TooManyRequests` | Rate limit exceeded. |
| `500` | `GeneralError` | Unexpected server error. Retry later; contact support if it persists. |

### Rate limits

Requests made with an API key are counted per organization in fixed windows.

| Limit | Default |
|---|---|
| Requests per window | 1,000 |
| Window length | 3,600 seconds (1 hour) |

Your organization may have a different limit; contact support to raise it. When you go over the limit you get:

```json
{
  "name": "TooManyRequests",
  "message": "Rate limit exceeded",
  "code": 429,
  "className": "too-many-requests",
  "data": {
    "limit": 1000,
    "current": 1001,
    "window": 3600,
    "retryAfter": 542
  }
}
```

`data.retryAfter` is the number of seconds until the window resets. Wait that long before retrying.

### Retrying safely

- Retry `429`, `500`, `502`, `503` and network errors with exponential backoff.
- `GET`, `PATCH` and `DELETE` are safe to retry. `POST` creates a new record each time: before retrying a `POST` that may have succeeded, list with a filter (for example by `email`) to check it does not already exist.
- Do not retry `400`, `401`, `403` or `404` without changing the request.

---

<a id="ai-and-llms"></a>

## Use with AI and LLMs

Source: https://www.achieveapex.com/docs/api-reference/ai-and-llms

The whole API reference is available in formats that ChatGPT, Claude, Cursor, Copilot and other AI tools can read, so they can write correct integrations for you.

### Downloads and machine-readable files

| File | URL | Use it for |
|---|---|---|
| Full reference (HTML, one page) | [`https://www.achieveapex.com/docs/api-reference.html`](https://www.achieveapex.com/docs/api-reference.html) | Paste the URL into ChatGPT or Claude so they read the whole reference. |
| Full reference (Markdown, one file) | [`https://www.achieveapex.com/docs/api-reference.md`](https://www.achieveapex.com/docs/api-reference.md) | Download and attach it to a chat, a Claude Project, a ChatGPT GPT, or add it to your repository for Cursor/Copilot. |
| OpenAPI 3.1 specification | [`https://www.achieveapex.com/docs/openapi.json`](https://www.achieveapex.com/docs/openapi.json) | Import into Postman, Insomnia or an SDK generator, or give it to an agent as a tool definition. |
| AI index of AchieveApex | [`https://www.achieveapex.com/llms.html`](https://www.achieveapex.com/llms.html) | Product and feature documentation for LLMs, with a link to this reference. |

Every page of this reference also has a **Copy page** menu (top right) to copy it as Markdown or open it directly in ChatGPT or Claude.

### Suggested prompt

```
You are helping me integrate with the AchieveApex REST API.
Read the reference at https://www.achieveapex.com/docs/api-reference.html
(base URL https://integrations.achieveapex.com, auth header x-api-key).
Use only endpoints and fields that appear in the reference. GET requests take
filters in the query string, never in a body.

Task: <describe what you want to build>
```

### Prefer an MCP connector?

If you want an AI assistant to **act** on your AchieveApex data (search contacts, send messages, create deals) instead of writing code, add the AchieveApex connector (MCP server) to Claude or ChatGPT and sign in with your AchieveApex account. The REST API in this reference is for your own code and integrations.

---

## Activities

<a id="activities"></a>

### Activities overview

Source: https://www.achieveapex.com/docs/api-reference/activities

An activity is a task, call, meeting or other to-do on your calendar, optionally linked to a deal, contact or company and assigned to a user. When the assigned user has a connected Google or Outlook calendar that syncs the activity's type, the activity is also created on that calendar.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/activities` | [List activities](#activities--list) |
| `GET` | `/activities/:id` | [Get an activity](#activities--get) |
| `POST` | `/activities` | [Create an activity](#activities--create) |
| `PATCH` | `/activities/:id` | [Update an activity](#activities--update) |
| `DELETE` | `/activities/:id` | [Delete an activity](#activities--delete) |

Reads are limited to your API key's organization. Pass `organization_id` as a filter to work with one organization.

#### The activity object

```json
{
  "id": 321,
  "organization_id": 456,
  "created_by_user_id": 789,
  "assigned_to_user_id": 790,
  "subject": "Follow-up call",
  "note": "Discuss pricing for the annual plan",
  "public_description": "Pricing follow-up",
  "location": "Zoom",
  "location_geocoded": null,
  "start_date": "2026-04-15",
  "start_time": "14:30:00",
  "end_date": "2026-04-15",
  "end_time": "15:00:00",
  "duration": 30,
  "deal_id": 55,
  "contact_id": 123,
  "company_id": 101,
  "activity_type": "call",
  "done": false,
  "attendees": [
    { "email": "jane@example.com", "name": "Jane Smith", "responseStatus": "needsAction" }
  ],
  "google_meet_link": null,
  "create_google_meet": false,
  "synced_to_calendar": true,
  "sync_status": "synced",
  "last_synced_at": "2026-04-01T09:00:05.000Z",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:05.000Z",
  "deleted_at": null,
  "company": { "id": 101, "name": "Acme Corporation", "organization_id": 456, "created_by_user_id": 789, "owned_by_user_id": 789 },
  "assignedTo": { "id": 790, "first_name": "Luis", "last_name": "Perez", "email": "luis@example.com" },
  "createdBy": { "id": 789, "first_name": "Ana", "last_name": "Lopez", "email": "ana@example.com" },
  "deal": { "id": 55, "name": "Annual plan", "amount": "12000.00", "currency_id": 2, "status": "open" },
  "contact": { "id": 123, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "2025550143" }
}
```

`company`, `assignedTo`, `createdBy`, `deal` and `contact` are embedded on get, create and update responses, and on list when you pass `fastJoinForActivityList=true`.

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the activity. Required on create. |
| `created_by_user_id` | integer \| null | Read-only. User who created the activity (the API key's user). |
| `assigned_to_user_id` | integer \| null | User the activity is assigned to. Calendar sync and reminders use this user. |
| `subject` | string | Title. Required on create. |
| `note` | string \| null | Internal notes. |
| `public_description` | string \| null | Description shown on the synced calendar event. |
| `location` | string \| null | Free-text location. |
| `location_geocoded` | object \| null | Any JSON describing the geocoded location. |
| `start_date` | string (date) | Start date, `YYYY-MM-DD`. |
| `start_time` | string | Start time. Send `HH:MM` (24 h); returned as `HH:MM:SS`. Times are in the organization's timezone. |
| `end_date` | string (date) | End date, `YYYY-MM-DD`. |
| `end_time` | string | End time. Send `HH:MM` (24 h); returned as `HH:MM:SS`. |
| `duration` | number | Duration in minutes. |
| `deal_id` | integer \| null | Linked [deal](#deals). |
| `contact_id` | integer \| null | Linked [contact](#contacts). |
| `company_id` | integer \| null | Linked [company](#companies). |
| `activity_type` | string | Type of activity. Default `call`. The built-in types are `call`, `meeting`, `task`, `deadline`, `email` and `lunch`; see also [Activity types](#activity-types). |
| `done` | boolean | Whether the activity is completed. Default `false`. |
| `attendees` | array \| null | People invited to the synced calendar event: `{ email, name, responseStatus }`. `email` is required; `responseStatus` is one of `needsAction`, `accepted`, `declined`, `tentative`. |
| `create_google_meet` | boolean \| null | Set to `true` to add a Google Meet link to the synced Google Calendar event. |
| `google_meet_link` | string \| null | Read-only. Google Meet link of the synced event. |
| `synced_to_calendar` | boolean | Read-only. Whether the activity is on the assignee's external calendar. Default `false`. |
| `sync_status` | string \| null | Read-only. `pending`, `synced`, `failed` or `not_synced`. |
| `last_synced_at` | string (date-time) \| null | Read-only. Last calendar sync time. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the activity is deleted. |

#### Side effects

- Create and update sync the activity to the assignee's connected calendar when their calendar integration syncs this `activity_type` and the activity is not `done`. Sync errors do not fail the request; they set `sync_status` to `failed`.
- When `assigned_to_user_id`, `start_date` and `start_time` are set and the start is in the future, the assignee gets a reminder 10 minutes before the start.
- Create and update trigger the organization's activity automations.

#### Related

- [Activity types](#activity-types)
- [Deals](#deals)
- [Contacts](#contacts)
- [Errors](#activities--errors)

<a id="activities--list"></a>

### List activities

Source: https://www.achieveapex.com/docs/api-reference/activities/list

Returns a paginated list of activities, with optional filters and a free-text search.

#### Endpoint

`GET /activities`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only activities of this organization. |
| any activity field | mixed | No | Filter with Feathers syntax, e.g. `done=false`, `assigned_to_user_id=790`, `deal_id=55`, `start_date[$gte]=2026-04-01`, `activity_type[$in][]=call`. |
| `searchTerm` | string | No | Case-insensitive match on subject, note, public description, location and the linked contact, deal and company. |
| `fastJoinForActivityList` | string | No | Set to `true` to embed `company`, `assignedTo`, `createdBy`, `deal` and `contact`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[start_date]=1`. With `searchTerm` the default is `created_at` descending. |
| `$select[]` | string | No | Only return these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/activities \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'done=false' \
  --data-urlencode 'start_date[$gte]=2026-04-01' \
  --data-urlencode 'fastJoinForActivityList=true' \
  --data-urlencode '$sort[start_date]=1' \
  --data-urlencode '$limit=25'
```

#### Response

```json
{
  "total": 1,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 321,
      "organization_id": 456,
      "assigned_to_user_id": 790,
      "subject": "Follow-up call",
      "start_date": "2026-04-15",
      "start_time": "14:30:00",
      "end_date": "2026-04-15",
      "end_time": "15:00:00",
      "duration": 30,
      "deal_id": 55,
      "contact_id": 123,
      "activity_type": "call",
      "done": false,
      "deleted_at": null,
      "assignedTo": { "id": 790, "first_name": "Luis", "last_name": "Perez", "email": "luis@example.com" },
      "contact": { "id": 123, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "2025550143" }
    }
  ]
}
```

Each item is a full [activity object](#activities); it is shortened here.

<a id="activities--get"></a>

### Get an activity

Source: https://www.achieveapex.com/docs/api-reference/activities/get

Returns one activity by ID, with `company`, `assignedTo`, `createdBy`, `deal` and `contact` embedded.

#### Endpoint

`GET /activities/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/activities/321 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [activity object](#activities).

```json
{
  "id": 321,
  "organization_id": 456,
  "created_by_user_id": 789,
  "assigned_to_user_id": 790,
  "subject": "Follow-up call",
  "note": "Discuss pricing for the annual plan",
  "start_date": "2026-04-15",
  "start_time": "14:30:00",
  "end_date": "2026-04-15",
  "end_time": "15:00:00",
  "duration": 30,
  "deal_id": 55,
  "contact_id": 123,
  "company_id": 101,
  "activity_type": "call",
  "done": false,
  "sync_status": "synced",
  "deleted_at": null,
  "assignedTo": { "id": 790, "first_name": "Luis", "last_name": "Perez", "email": "luis@example.com" },
  "createdBy": { "id": 789, "first_name": "Ana", "last_name": "Lopez", "email": "ana@example.com" },
  "deal": { "id": 55, "name": "Annual plan", "amount": "12000.00", "currency_id": 2, "status": "open" },
  "contact": { "id": 123, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "2025550143" },
  "company": { "id": 101, "name": "Acme Corporation", "organization_id": 456, "created_by_user_id": 789, "owned_by_user_id": 789 }
}
```

<a id="activities--create"></a>

### Create an activity

Source: https://www.achieveapex.com/docs/api-reference/activities/create

Creates an activity. See [side effects](#activities) for calendar sync, reminders and automations.

#### Endpoint

`POST /activities`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the activity in. |
| `subject` | string | Yes | Title. |
| `activity_type` | string | No | Default `call`. Built-in types: `call`, `meeting`, `task`, `deadline`, `email`, `lunch`. |
| `assigned_to_user_id` | integer | No | Assignee. |
| `start_date` | string | No | `YYYY-MM-DD`. |
| `start_time` | string | No | `HH:MM`, 24 h. |
| `end_date` | string | No | `YYYY-MM-DD`. |
| `end_time` | string | No | `HH:MM`, 24 h. |
| `duration` | number | No | Minutes. |
| `deal_id` | integer | No | Linked deal. |
| `contact_id` | integer | No | Linked contact. |
| `company_id` | integer | No | Linked company. |
| `note` | string | No | Internal notes. |
| `public_description` | string | No | Description for the calendar event. |
| `location` | string | No | Location. |
| `done` | boolean | No | Default `false`. |
| `attendees` | array | No | `{ email, name, responseStatus }` items invited to the synced event. |
| `create_google_meet` | boolean | No | Add a Google Meet link to the synced Google Calendar event. |

Fields not in the [activity object](#activities) are rejected. `created_by_user_id` is set to the API key's user.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/activities \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "subject": "Demo meeting",
    "activity_type": "meeting",
    "assigned_to_user_id": 790,
    "start_date": "2026-04-20",
    "start_time": "10:00",
    "end_date": "2026-04-20",
    "end_time": "10:45",
    "duration": 45,
    "contact_id": 123,
    "attendees": [{ "email": "john.doe@example.com", "name": "John Doe" }],
    "create_google_meet": true
  }'
```

#### Response

Returns the created [activity object](#activities) with linked records embedded.

```json
{
  "id": 322,
  "organization_id": 456,
  "created_by_user_id": 789,
  "assigned_to_user_id": 790,
  "subject": "Demo meeting",
  "activity_type": "meeting",
  "start_date": "2026-04-20",
  "start_time": "10:00:00",
  "end_date": "2026-04-20",
  "end_time": "10:45:00",
  "duration": 45,
  "contact_id": 123,
  "done": false,
  "attendees": [{ "email": "john.doe@example.com", "name": "John Doe" }],
  "create_google_meet": true,
  "synced_to_calendar": false,
  "created_at": "2026-04-02T12:00:00.000Z",
  "updated_at": "2026-04-02T12:00:00.000Z",
  "deleted_at": null,
  "contact": { "id": 123, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "2025550143" }
}
```

Calendar sync runs right after the activity is saved, so the response can show the state before the sync finished. Get the activity again to read `sync_status` and `google_meet_link`.

<a id="activities--update"></a>

### Update an activity

Source: https://www.achieveapex.com/docs/api-reference/activities/update

Partially updates an activity. Only the fields you send change. Use it to reschedule, reassign or mark an activity as done.

#### Endpoint

`PATCH /activities/:id`

#### Body

Any writable field of the [activity object](#activities). Fields not in the object are rejected.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/activities/321 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "done": true
  }'
```

#### Response

Returns the updated [activity object](#activities) with linked records embedded.

```json
{
  "id": 321,
  "organization_id": 456,
  "subject": "Follow-up call",
  "activity_type": "call",
  "done": true,
  "updated_at": "2026-04-15T15:05:00.000Z",
  "deleted_at": null
}
```

Changing the date, time or assignee re-syncs the calendar event and reschedules the reminder.

<a id="activities--delete"></a>

### Delete an activity

Source: https://www.achieveapex.com/docs/api-reference/activities/delete

Deletes an activity. This is a soft delete: the activity gets a `deleted_at` timestamp and no longer appears in list or get. Its event is removed from the synced external calendar and its pending reminder is cancelled.

#### Endpoint

`DELETE /activities/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/activities/321 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [activity object](#activities) with `deleted_at` set.

```json
{
  "id": 321,
  "organization_id": 456,
  "subject": "Follow-up call",
  "deleted_at": "2026-04-16T08:00:00.000Z"
}
```

<a id="activities--errors"></a>

### Activities errors

Source: https://www.achieveapex.com/docs/api-reference/activities/errors

Errors use the standard Feathers error format.

```json
{
  "name": "BadRequest",
  "message": "validation failed",
  "code": 400,
  "className": "bad-request"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query, e.g. an unknown field, a time not in `HH:MM` format, or an invalid `responseStatus`. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, or the record belongs to an organization the key cannot access. |
| `404 Not Found` | The activity does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error. Calendar sync failures do not cause errors; they set `sync_status` to `failed`. |

---

## Activity types

<a id="activity-types"></a>

### Activity types overview

Source: https://www.achieveapex.com/docs/api-reference/activity-types

Activity types are the custom categories (with a color and icon) your organization defines for [activities](#activities), on top of the built-in ones.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/activity-types` | [List activity types](#activity-types--list) |
| `GET` | `/activity-types/:id` | [Get an activity type](#activity-types--get) |
| `POST` | `/activity-types` | [Create an activity type](#activity-types--create) |
| `PATCH` | `/activity-types/:id` | [Update an activity type](#activity-types--update) |
| `DELETE` | `/activity-types/:id` | [Delete an activity type](#activity-types--delete) |

Reads are limited to your API key's organization. Pass `organization_id` as a filter to work with one organization.

#### The activity type object

```json
{
  "id": 5,
  "name": "Site visit",
  "color": "#8B5CF6",
  "icon_key": "map-pin",
  "organization_id": 456,
  "created_at": "2026-03-10T14:22:17.562Z",
  "updated_at": "2026-03-10T14:22:17.562Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Display name. Required on create. |
| `color` | string \| null | Color, e.g. a hex code such as `#8B5CF6`. |
| `icon_key` | string \| null | Name of the icon shown in the app, e.g. `map-pin`. |
| `organization_id` | integer | Organization that owns the type. Required on create. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the type is deleted. |

#### Related

- [Activities](#activities)
- [Errors](#activity-types--errors)

<a id="activity-types--list"></a>

### List activity types

Source: https://www.achieveapex.com/docs/api-reference/activity-types/list

Returns a paginated list of activity types.

#### Endpoint

`GET /activity-types`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only types of this organization. |
| any activity type field | mixed | No | Filter with Feathers syntax, e.g. `name=Site visit`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/activity-types \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode '$sort[name]=1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 5,
      "name": "Site visit",
      "color": "#8B5CF6",
      "icon_key": "map-pin",
      "organization_id": 456,
      "created_at": "2026-03-10T14:22:17.562Z",
      "updated_at": "2026-03-10T14:22:17.562Z",
      "deleted_at": null
    }
  ]
}
```

<a id="activity-types--get"></a>

### Get an activity type

Source: https://www.achieveapex.com/docs/api-reference/activity-types/get

Returns one activity type by ID.

#### Endpoint

`GET /activity-types/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/activity-types/5 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [activity type object](#activity-types).

```json
{
  "id": 5,
  "name": "Site visit",
  "color": "#8B5CF6",
  "icon_key": "map-pin",
  "organization_id": 456,
  "created_at": "2026-03-10T14:22:17.562Z",
  "updated_at": "2026-03-10T14:22:17.562Z",
  "deleted_at": null
}
```

<a id="activity-types--create"></a>

### Create an activity type

Source: https://www.achieveapex.com/docs/api-reference/activity-types/create

Creates an activity type.

#### Endpoint

`POST /activity-types`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the type in. |
| `name` | string | Yes | Display name. |
| `color` | string | No | Color, e.g. `#8B5CF6`. |
| `icon_key` | string | No | Icon name, e.g. `map-pin`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/activity-types \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Site visit",
    "color": "#8B5CF6",
    "icon_key": "map-pin"
  }'
```

#### Response

```json
{
  "id": 6,
  "name": "Site visit",
  "color": "#8B5CF6",
  "icon_key": "map-pin",
  "organization_id": 456,
  "created_at": "2026-04-05T09:30:22.451Z",
  "updated_at": "2026-04-05T09:30:22.451Z",
  "deleted_at": null
}
```

<a id="activity-types--update"></a>

### Update an activity type

Source: https://www.achieveapex.com/docs/api-reference/activity-types/update

Partially updates an activity type. Only the fields you send change.

#### Endpoint

`PATCH /activity-types/:id`

#### Body

Any of `name`, `color`, `icon_key`.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/activity-types/5 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#10B981"
  }'
```

#### Response

Returns the updated [activity type object](#activity-types).

```json
{
  "id": 5,
  "name": "Site visit",
  "color": "#10B981",
  "icon_key": "map-pin",
  "organization_id": 456,
  "created_at": "2026-03-10T14:22:17.562Z",
  "updated_at": "2026-04-06T10:00:00.000Z",
  "deleted_at": null
}
```

<a id="activity-types--delete"></a>

### Delete an activity type

Source: https://www.achieveapex.com/docs/api-reference/activity-types/delete

Deletes an activity type. This is a soft delete: the type gets a `deleted_at` timestamp and no longer appears in list or get. Existing activities are not changed.

#### Endpoint

`DELETE /activity-types/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/activity-types/5 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [activity type object](#activity-types) with `deleted_at` set.

```json
{
  "id": 5,
  "name": "Site visit",
  "color": "#8B5CF6",
  "icon_key": "map-pin",
  "organization_id": 456,
  "created_at": "2026-03-10T14:22:17.562Z",
  "updated_at": "2026-04-07T10:00:00.000Z",
  "deleted_at": "2026-04-07T10:00:00.000Z"
}
```

<a id="activity-types--errors"></a>

### Activity types errors

Source: https://www.achieveapex.com/docs/api-reference/activity-types/errors

Errors use the standard Feathers error format.

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query, e.g. missing `name` or an unknown field. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, or the record belongs to an organization the key cannot access. |
| `404 Not Found` | The activity type does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error. |

---

## AI Assistant Skills

<a id="ai-assistant-skills"></a>

### AI Assistant Skills overview

Source: https://www.achieveapex.com/docs/api-reference/ai-assistant-skills

A skill is a focused block of knowledge or procedure attached to an AI assistant. The assistant loads it only when `when_to_use` matches the situation, which keeps the main instructions short.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/ai-assistant-skills` | [List skills](#ai-assistant-skills--list) |
| `GET` | `/ai-assistant-skills/:id` | [Get a skill](#ai-assistant-skills--get) |
| `POST` | `/ai-assistant-skills` | [Create a skill](#ai-assistant-skills--create) |
| `PATCH` | `/ai-assistant-skills/:id` | [Update a skill](#ai-assistant-skills--update) |
| `DELETE` | `/ai-assistant-skills/:id` | [Delete a skill](#ai-assistant-skills--delete) |

Reads are limited to your API key's organization.

#### The skill object

```json
{
  "id": 8801,
  "organization_id": 27,
  "assistant_id": 123,
  "name": "Refund Policy",
  "content": "Customers can request a refund within 30 days of purchase...",
  "when_to_use": "Use when the customer asks about refunds, cancellations, or guarantees.",
  "created_at": "2026-04-25T12:00:00.000Z",
  "updated_at": "2026-04-25T12:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the skill. Required on create with an API key (your key's organization). |
| `assistant_id` | integer | Required. [AI assistant](#ai-assistants) that uses the skill; must belong to the same organization. |
| `name` | string | Required. Skill name. |
| `content` | string | Required. Instructions or knowledge, in Markdown or plain text. |
| `when_to_use` | string | Required. Tells the assistant when to load the skill. |
| `created_at` | string (date-time) | Read-only. Creation timestamp. |
| `updated_at` | string (date-time) | Read-only. Last update timestamp. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the skill is deleted. |

Creating, updating or deleting a skill of a voice assistant marks the assistant's voice configuration for re-sync (`telnyx_ai_assistant_config.sync_status: "pending"`), except on the `openai_realtime_sip` runtime.

#### Related

- [AI Assistants](#ai-assistants)

<a id="ai-assistant-skills--list"></a>

### List skills

Source: https://www.achieveapex.com/docs/api-reference/ai-assistant-skills/list

Return the skills of your organization, usually filtered by assistant.

#### Endpoint

`GET /ai-assistant-skills`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `assistant_id` | integer | No | Skills of one assistant. |
| `name` | string | No | Exact name match. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | integer | No | `1` ascending, `-1` descending, e.g. `$sort[created_at]=1`. |
| `$select[]` | string | No | Return only these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/ai-assistant-skills \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'assistant_id=123' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[created_at]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 701,
      "organization_id": 27,
      "assistant_id": 123,
      "name": "Refund Policy",
      "content": "Refunds are available within 30 days...",
      "when_to_use": "Use when customers ask about refunds.",
      "created_at": "2026-04-25T15:20:00.000Z",
      "updated_at": "2026-04-25T15:20:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="ai-assistant-skills--get"></a>

### Get a skill

Source: https://www.achieveapex.com/docs/api-reference/ai-assistant-skills/get

Retrieve one skill by ID.

#### Endpoint

`GET /ai-assistant-skills/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/ai-assistant-skills/701 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 701,
  "organization_id": 27,
  "assistant_id": 123,
  "name": "Refund Policy",
  "content": "Refunds are available within 30 days of purchase when the customer provides an order number.",
  "when_to_use": "Use when the customer asks about refunds, cancellations, or returns.",
  "created_at": "2026-04-20T14:21:00.000Z",
  "updated_at": "2026-04-20T14:21:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404` | The skill does not exist, is deleted or belongs to another organization. |

<a id="ai-assistant-skills--create"></a>

### Create a skill

Source: https://www.achieveapex.com/docs/api-reference/ai-assistant-skills/create

Create a skill and attach it to an assistant.

#### Endpoint

`POST /ai-assistant-skills`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your API key's organization ID. |
| `assistant_id` | integer | Yes | Assistant that uses the skill (same organization). |
| `name` | string | Yes | Skill name. |
| `when_to_use` | string | Yes | When the assistant should load the skill. |
| `content` | string | Yes | Instructions or knowledge (Markdown or plain text). |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/ai-assistant-skills \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "assistant_id": 123,
    "name": "Pricing Policy",
    "when_to_use": "Use when the customer asks about billing, discounts, or plan changes.",
    "content": "Annual plans can receive a 10% discount. Enterprise pricing must be quoted by sales."
  }'
```

#### Response

```json
{
  "id": 901,
  "organization_id": 27,
  "assistant_id": 123,
  "name": "Pricing Policy",
  "when_to_use": "Use when the customer asks about billing, discounts, or plan changes.",
  "content": "Annual plans can receive a 10% discount. Enterprise pricing must be quoted by sales.",
  "created_at": "2026-04-25T14:10:00.000Z",
  "updated_at": "2026-04-25T14:10:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400` | A required field is missing, or `assistant_id` does not exist or belongs to another organization. |
| `403` | `organization_id` is missing or is not your API key's organization. |

<a id="ai-assistant-skills--update"></a>

### Update a skill

Source: https://www.achieveapex.com/docs/api-reference/ai-assistant-skills/update

Partially update a skill.

#### Endpoint

`PATCH /ai-assistant-skills/:id`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Skill name. |
| `content` | string | No | Instructions or knowledge. |
| `when_to_use` | string | No | When the assistant should load the skill. |

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistant-skills/801 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "when_to_use": "Use when a customer asks about onboarding milestones or rollout responsibilities.",
    "content": "Enterprise onboarding includes kickoff, workspace configuration, integration mapping, training and launch support."
  }'
```

#### Response

The updated [skill object](#ai-assistant-skills).

```json
{
  "id": 801,
  "organization_id": 27,
  "assistant_id": 123,
  "name": "Enterprise onboarding",
  "content": "Enterprise onboarding includes kickoff, workspace configuration, integration mapping, training and launch support.",
  "when_to_use": "Use when a customer asks about onboarding milestones or rollout responsibilities.",
  "created_at": "2026-04-01T10:00:00.000Z",
  "updated_at": "2026-04-03T15:30:00.000Z",
  "deleted_at": null
}
```

<a id="ai-assistant-skills--delete"></a>

### Delete a skill

Source: https://www.achieveapex.com/docs/api-reference/ai-assistant-skills/delete

Delete a skill. This is a soft delete: the skill gets `deleted_at` and no longer appears in list or get, and the assistant stops using it.

#### Endpoint

`DELETE /ai-assistant-skills/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/ai-assistant-skills/9001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 9001,
  "organization_id": 27,
  "assistant_id": 123,
  "name": "Warranty Policy",
  "content": "All annual plans include a 30-day satisfaction guarantee.",
  "when_to_use": "Use when the user asks about refunds or warranty terms.",
  "created_at": "2026-04-20T12:00:00.000Z",
  "updated_at": "2026-04-26T09:00:00.000Z",
  "deleted_at": "2026-04-26T09:00:00.000Z"
}
```

---

## AI Assistants

<a id="ai-assistants"></a>

### AI Assistants overview

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants

An AI assistant answers conversations, support tickets, internal AI chat or voice calls on behalf of your organization. Everything you can configure on the assistant settings page (instructions, handoff, follow-ups, tools, schedule, voice) is stored on the assistant record, so you can manage it entirely through this resource.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/ai-assistants` | [List AI assistants](#ai-assistants--list) |
| `GET` | `/ai-assistants/:id` | [Get an AI assistant](#ai-assistants--get) |
| `POST` | `/ai-assistants` | [Create an AI assistant](#ai-assistants--create) |
| `PATCH` | `/ai-assistants/:id` | [Update an AI assistant](#ai-assistants--update) |
| `PATCH` | `/ai-assistants/:id` | [Configure a voice assistant](#ai-assistants--voice) |
| `DELETE` | `/ai-assistants/:id` | [Delete an AI assistant](#ai-assistants--delete) |
| `GET` | `/ai-assistants-change-history` | [List configuration history](#ai-assistants--history) |
| `GET` | `/ai-assistants-change-history/:id` | [Get a history entry](#ai-assistants--history-get) |
| `POST` | `/ai-assistants-restore-from-changes-history` | [Restore a configuration version](#ai-assistants--restore) |
| `GET` | `/telnyx-ai-models` | [List voice LLM models](#ai-assistants--voice-models) |
| `GET` | `/telnyx-ai-voices` | [List voices](#ai-assistants--voice-voices) |
| `GET` | `/telnyx-ai-transcription-languages` | [List transcription languages](#ai-assistants--voice-transcription-languages) |

Your API key is scoped to one organization: list and get only return assistants of that organization, and `organization_id` must be your organization's ID when you create one.

#### The AI assistant object

```json
{
  "id": 321,
  "organization_id": 27,
  "created_by_user_id": 45,
  "name": "Sales Assistant",
  "description": "Answers sales questions and routes qualified leads",
  "assistant_type": "conversation",
  "ai_model_id": 12,
  "connection": "system",
  "specific_openai_secret_key": null,
  "timezone": "America/New_York",
  "instructions_language": "ENG",
  "instructions": "You are a helpful sales assistant.",
  "is_easy_mode": false,
  "easy_mode_config": null,
  "version_id": "9b1d3c2e-6f0a-4d5e-8a7b-1c2d3e4f5a6b",
  "disable_reply": false,
  "analyze_images": true,
  "enable_message_burst_handling": false,
  "can_send_images": false,
  "can_send_audio": false,
  "can_send_video": false,
  "can_send_documents": false,
  "additional_json_keys": [],
  "advanced_options": {
    "verbosity": "low",
    "reasoning_effort": "none",
    "tools": { "search_product": false, "web_search": false },
    "conversation_summary_config": { "enabled": true }
  },
  "access_permissions_contact": "read",
  "access_permissions_deals": "none",
  "access_permissions_customer_support": "none",
  "access_permissions_automations": [],
  "human_handoff_config": { "rules": [] },
  "external_handoff_targets": null,
  "ai_assistant_handoff_config": { "rules": [] },
  "ai_safeguards": null,
  "follow_up_config": { "enabled": false, "follow_up_limit": 3, "rules": [] },
  "api_tools": [],
  "internal_tools": { "enabled": false, "tools": {} },
  "response_config": {
    "response_mode": "single",
    "max_messages_per_response": 1,
    "delay_between_messages_ms": 1000
  },
  "agent_loop_config": null,
  "schedule_config": { "always_on": true },
  "mcp_tools": [],
  "voice_enabled": false,
  "telnyx_ai_assistant_config": null,
  "acting_user_id": null,
  "created_at": "2026-04-25T12:00:00.000Z",
  "updated_at": "2026-04-25T12:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Required on create. Organization that owns the assistant; must be your API key's organization. |
| `created_by_user_id` | integer | ID of the user who created the assistant. Not set automatically for API key requests. |
| `name` | string | Required on create. Display name. |
| `description` | string | Short description. |
| `assistant_type` | string | One of `conversation`, `support-ticket`, `helpdesk`, `ai-chat`, `voice`. |
| `ai_model_id` | integer | Required on create. ID from [AI Models](#ai-models). Use a model whose `active_in_*` flag matches the assistant type. |
| `connection` | string | Required on create. Model credential source: `system`, `organization` or `specific`. The server forces `system` unless your plan includes your own provider credentials. |
| `specific_openai_secret_key` | string \| null | Provider key used when `connection` is `specific`. Treat it as a secret: it is returned as stored. |
| `timezone` | string \| null | IANA timezone used by schedules and time-aware behavior. Default `UTC`, max 50 characters. |
| `instructions` | string \| null | Full system instructions (prompt). In guided mode this holds the generated prompt. |
| `instructions_language` | string | `ENG` or `ESP`. |
| `is_easy_mode` | boolean | Whether guided mode is used. Default `true`. |
| `easy_mode_config` | object \| null | Guided-mode source: `brand`, `assistantName`, `role`, and the arrays `objectives`, `restrictions`, `additionalInstructions`, `products`, `promotions`, `conversationFlows`, `companyLocations`, `dialectSections`, `dynamicSections`. |
| `version_id` | string \| null | Read-only. New UUID generated on every create and update. |
| `disable_reply` | boolean | When `true` the assistant does not send replies. Default `false`. |
| `analyze_images` | boolean | Let the assistant read images sent by the contact. Default `true`. |
| `enable_message_burst_handling` | boolean | Group rapid incoming messages before replying. Default `false`. |
| `can_send_images` | boolean | Let the assistant send image media. Default `false`. Turned on automatically when `instructions` reference an image from the assistant media library. |
| `can_send_audio` | boolean | Let the assistant send audio media. Default `false`. Auto-enabled like `can_send_images`. |
| `can_send_video` | boolean | Let the assistant send video media. Default `false`. Auto-enabled like `can_send_images`. |
| `can_send_documents` | boolean | Let the assistant send documents. Default `false`. Auto-enabled like `can_send_images`. |
| `additional_json_keys` | array | Extra structured-output keys the assistant fills on each reply. |
| `advanced_options` | object | `verbosity` (`low`, `medium`, `high`), `reasoning_effort` (`none`, `minimal`, `low`, `medium`, `high`), `tools` (`search_product`, `web_search`, `web_search_config`) and `conversation_summary_config` (`enabled`, `instructions`). Summaries are enabled by default for `conversation`, `support-ticket` and `ai-chat` assistants. |
| `access_permissions_contact` | string \| null | Contact access: `none`, `read` or `read_write`. Default `none`. |
| `access_permissions_deals` | string \| null | Deal access: `none`, `read` or `read_write`. Default `none`. |
| `access_permissions_customer_support` | string \| null | Ticket access: `none`, `read` or `read_write`. Default `none`. |
| `access_permissions_automations` | array \| null | Automations the assistant may run: `{ automation_id, when_to_use }` (both required). |
| `human_handoff_config` | object \| null | `rules` for handing off to team members. Each rule requires `name`, `instructions` and `team_members` (`{ user_id, weight }`, weight 0-100). See [Update](#ai-assistants--update). |
| `external_handoff_targets` | object \| null | Voice only. `rules` that transfer calls to an external number or SIP URI. Each rule requires `id`, `name`, `instructions`, `label`, `destination_type` (`external_number` or `sip_uri`). |
| `ai_assistant_handoff_config` | object \| null | `rules` for handing off to another assistant. Each rule requires `name`, `instructions`, `ai_assistant_id`. |
| `ai_safeguards` | object \| null | Per-assistant overrides of the loop and rate-limit safeguards. Missing or `null` keys use the system values. See [Update](#ai-assistants--update). |
| `follow_up_config` | object | `enabled`, `follow_up_limit` (default 3) and `rules` that send follow-ups when the contact stops replying. |
| `api_tools` | array \| null | [API tools](#api-tools) the assistant can call: `{ api_tool_id, description, when_to_use, config }`. |
| `internal_tools` | object \| null | `enabled`, a `tools` map of AchieveApex actions (`find_contact: true`, ...) and `track_conversation_event_config.event_definition_ids`. `ai-chat` and `helpdesk` assistants get a default tool set on create. |
| `response_config` | object \| null | `response_mode` (`single` or `multi`), `max_messages_per_response` (1-10), `delay_between_messages_ms` (500-5000), `allow_no_reply`, `no_reply_instructions`. |
| `agent_loop_config` | object \| null | Tool-calling loop limits: `max_iterations` (default 100) and `enable_clarification` (default `true`). |
| `schedule_config` | object \| null | Availability: `always_on`, `weekly_schedule`, `out_of_schedule_action` (`message` or `handoff`), `schedule_not_available_message`, `schedule_handoff_config`. |
| `mcp_tools` | array \| null | External MCP servers. See [MCP Tool Connections](#mcp-tool-connections). |
| `voice_enabled` | boolean \| null | Read as `true` for every `voice` assistant (set automatically). |
| `telnyx_ai_assistant_config` | object \| null | Voice runtime configuration. See [Configure a voice assistant](#ai-assistants--voice). |
| `acting_user_id` | integer \| null | Voice only. User whose identity the assistant uses for write actions during calls. |
| `created_at` | string (date-time) | Read-only. Creation timestamp. |
| `updated_at` | string (date-time) | Read-only. Last update timestamp. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the assistant is deleted. |

`GET /ai-assistants/:id` and `PATCH /ai-assistants/:id` responses also include a computed, read-only `ai_safeguards_system` object (`defaults` and `ranges` of every safeguard). Do not send it back.

#### Related

- [AI Models](#ai-models)
- [AI Assistant Skills](#ai-assistant-skills)
- [API Tools](#api-tools)
- [MCP Tool Connections](#mcp-tool-connections)

<a id="ai-assistants--list"></a>

### List AI assistants

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/list

Return the AI assistants of your organization, with optional filters and pagination.

#### Endpoint

`GET /ai-assistants`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `assistant_type` | string | No | `conversation`, `support-ticket`, `helpdesk`, `ai-chat` or `voice`. |
| `name` | string | No | Exact name match. |
| `ai_model_id` | integer | No | Assistants using this model. |
| `id` | integer | No | Exact ID, or operators such as `id[$ne]=123` or `id[$in][]=1&id[$in][]=2`. |
| `$limit` | integer | No | Page size. Default 10, max 50. Use `0` to get only `total`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | integer | No | `1` ascending, `-1` descending, e.g. `$sort[name]=1`. |
| `$select[]` | string | No | Return only these fields. |

Any other field of the [AI assistant object](#ai-assistants) can be used as an exact-match filter. Results are always limited to your API key's organization and exclude deleted assistants.

#### Request

```bash
curl -G https://integrations.achieveapex.com/ai-assistants \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'assistant_type=conversation' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$sort[name]=1'
```

Count voice assistants without loading them:

```bash
curl -G https://integrations.achieveapex.com/ai-assistants \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'assistant_type=voice' \
  --data-urlencode '$limit=0'
```

#### Response

```json
{
  "total": 2,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "organization_id": 27,
      "name": "Sales Assistant",
      "assistant_type": "conversation",
      "ai_model_id": 8,
      "connection": "system",
      "timezone": "America/New_York",
      "is_easy_mode": true,
      "voice_enabled": false,
      "created_at": "2026-04-01T12:00:00.000Z",
      "updated_at": "2026-04-02T15:30:00.000Z",
      "deleted_at": null
    }
  ]
}
```

Each item is a full [AI assistant object](#ai-assistants); the example is shortened.

<a id="ai-assistants--get"></a>

### Get an AI assistant

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/get

Retrieve one AI assistant with its full configuration.

#### Endpoint

`GET /ai-assistants/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | integer | Yes | AI assistant ID. |

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `$syncFromTelnyx` | boolean | No | Voice assistants only. Refreshes the stored `telnyx_ai_assistant_config` from the voice provider before returning it. |
| `$select[]` | string | No | Return only these fields. |

#### Request

```bash
curl https://integrations.achieveapex.com/ai-assistants/123 \
  -H "x-api-key: YOUR_API_KEY"
```

Refresh a voice assistant from the voice provider:

```bash
curl -G https://integrations.achieveapex.com/ai-assistants/501 \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode '$syncFromTelnyx=true'
```

#### Response

```json
{
  "id": 123,
  "organization_id": 27,
  "name": "Sales Assistant",
  "assistant_type": "conversation",
  "ai_model_id": 9,
  "connection": "system",
  "timezone": "America/New_York",
  "instructions_language": "ENG",
  "instructions": "You are a helpful sales assistant.",
  "is_easy_mode": false,
  "advanced_options": { "verbosity": "low", "reasoning_effort": "none", "tools": {} },
  "human_handoff_config": { "rules": [] },
  "ai_assistant_handoff_config": { "rules": [] },
  "follow_up_config": { "enabled": false, "follow_up_limit": 3, "rules": [] },
  "schedule_config": { "always_on": true },
  "ai_safeguards": { "max_responses_per_minute": 10 },
  "ai_safeguards_system": {
    "defaults": { "max_responses_per_minute": 6, "max_executions_per_hour": 60 },
    "ranges": { "max_responses_per_minute": { "type": "integer", "minimum": 2, "maximum": 30 } }
  },
  "created_at": "2026-04-20T12:00:00.000Z",
  "updated_at": "2026-04-20T12:30:00.000Z",
  "deleted_at": null
}
```

Returns the full [AI assistant object](#ai-assistants) (shortened above) plus the read-only `ai_safeguards_system` object with the system default and allowed range of every safeguard.

#### Errors

| Status | When |
|---|---|
| `404` | The assistant does not exist, is deleted, or belongs to another organization. |

<a id="ai-assistants--create"></a>

### Create an AI assistant

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/create

Create an assistant for conversations, support tickets, the help desk, internal AI chat or voice calls.

#### Endpoint

`POST /ai-assistants`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your API key's organization ID. |
| `name` | string | Yes | Display name. |
| `ai_model_id` | integer | Yes | Model ID from [AI Models](#ai-models). |
| `connection` | string | Yes | `system`, `organization` or `specific`. The server stores `system` unless your plan includes your own provider credentials. |
| `assistant_type` | string | No | `conversation`, `support-ticket`, `helpdesk`, `ai-chat` or `voice`. |
| `description` | string | No | Short description. |
| `instructions` | string | No | Full system instructions. |
| `instructions_language` | string | No | `ENG` or `ESP`. |
| `is_easy_mode` | boolean | No | Guided mode. Default `true`; send `false` when you write `instructions` yourself. |
| `easy_mode_config` | object \| null | No | Guided-mode source. Use `null` for advanced mode. |
| `timezone` | string | No | IANA timezone. Default `UTC`. |
| `specific_openai_secret_key` | string | No | Provider key used when `connection` is `specific`. |
| `telnyx_ai_assistant_config` | object | No | Voice configuration. See [Configure a voice assistant](#ai-assistants--voice). |

Every other writable field of the [AI assistant object](#ai-assistants) can also be sent on create; the same shapes as in [Update an AI assistant](#ai-assistants--update) apply. Unknown top-level fields are rejected.

What the server does on create:

- Generates `version_id`.
- `voice` assistants get `voice_enabled: true` and, when you send no voice config, `telnyx_ai_assistant_config: { "sync_status": "pending", "voice_mode": "unified" }`. The voice agent is then synced with the voice provider.
- `ai-chat` and `helpdesk` assistants get a default `internal_tools` set (it replaces any `internal_tools` you send).
- `conversation`, `support-ticket` and `ai-chat` assistants get `advanced_options.conversation_summary_config.enabled: true` unless you set it.
- Media send flags (`can_send_images`, ...) are turned on when `instructions` reference media from the assistant media library.
- `created_by_user_id` is not filled in for API key requests, and no [change history](#ai-assistants--history) entry is recorded.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/ai-assistants \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Sales Assistant",
    "assistant_type": "conversation",
    "ai_model_id": 12,
    "connection": "system",
    "timezone": "America/New_York",
    "instructions_language": "ENG",
    "is_easy_mode": true,
    "easy_mode_config": {
      "brand": "Acme",
      "assistantName": "Ava",
      "role": "Sales assistant",
      "objectives": [{ "id": "1", "value": "Qualify inbound leads" }],
      "restrictions": [{ "id": "1", "value": "Do not invent pricing" }],
      "additionalInstructions": [{ "id": "1", "value": "Use concise answers" }],
      "products": [],
      "promotions": [],
      "conversationFlows": [],
      "companyLocations": [],
      "dialectSections": [],
      "dynamicSections": []
    },
    "instructions": "## Your identity\nYou are Ava, the sales assistant of Acme..."
  }'
```

Create a voice assistant:

```bash
curl -X POST https://integrations.achieveapex.com/ai-assistants \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Voice Receptionist",
    "assistant_type": "voice",
    "ai_model_id": 18,
    "connection": "system",
    "timezone": "America/New_York",
    "is_easy_mode": false,
    "instructions": "You answer calls for Acme. Be brief.",
    "telnyx_ai_assistant_config": {
      "sync_status": "pending",
      "voice_runtime": "telnyx_builtin",
      "voice_mode": "unified",
      "greeting": "Hi, thanks for calling Acme. How can I help?"
    }
  }'
```

#### Response

The created [AI assistant object](#ai-assistants) (shortened):

```json
{
  "id": 345,
  "organization_id": 27,
  "name": "Sales Assistant",
  "assistant_type": "conversation",
  "ai_model_id": 12,
  "connection": "system",
  "timezone": "America/New_York",
  "instructions_language": "ENG",
  "is_easy_mode": true,
  "version_id": "0c8a6d3e-2b1f-4e5a-9c7d-3f2e1a0b9c8d",
  "advanced_options": {
    "verbosity": "low",
    "reasoning_effort": "none",
    "tools": {},
    "conversation_summary_config": { "enabled": true }
  },
  "created_at": "2026-04-25T14:00:00.000Z",
  "updated_at": "2026-04-25T14:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400` | A required field is missing, a value is outside its enum or range, an unknown top-level field is sent, or a handoff rule references an invalid user or assistant. |
| `403` | `organization_id` is not your API key's organization. |

<a id="ai-assistants--update"></a>

### Update an AI assistant

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/update

Partially update an assistant. This is how you configure through the API everything the assistant settings page offers. Send only the fields you want to change; object fields such as `human_handoff_config` are replaced as a whole.

#### Endpoint

`PATCH /ai-assistants/:id`

#### Body

Any writable field of the [AI assistant object](#ai-assistants). Unknown top-level fields are rejected; do not send read-only fields such as `id`, `version_id` or `ai_safeguards_system`.

| Name | Type | Description |
|---|---|---|
| `name` | string | Display name. |
| `description` | string | Short description. |
| `ai_model_id` | integer | Model from [AI Models](#ai-models). |
| `connection` | string | `system`, `organization` or `specific` (forced to `system` unless your plan includes your own credentials). |
| `specific_openai_secret_key` | string \| null | Provider key used when `connection` is `specific`. |
| `timezone` | string \| null | IANA timezone. |
| `instructions` | string \| null | Full system instructions. |
| `instructions_language` | string | `ENG` or `ESP`. |
| `is_easy_mode` | boolean | Guided mode. |
| `easy_mode_config` | object \| null | Guided-mode source. |
| `human_handoff_config` | object \| null | Handoff to team members. |
| `ai_assistant_handoff_config` | object \| null | Handoff to another assistant. |
| `external_handoff_targets` | object \| null | Voice only: transfers to external numbers or SIP URIs. |
| `follow_up_config` | object | Follow-up rules. |
| `access_permissions_automations` | array \| null | Automations the assistant can run. |
| `access_permissions_contact` | string \| null | `none`, `read` or `read_write`. |
| `access_permissions_deals` | string \| null | `none`, `read` or `read_write`. |
| `access_permissions_customer_support` | string \| null | `none`, `read` or `read_write`. |
| `advanced_options` | object | Verbosity, reasoning effort, tools and conversation summaries. |
| `additional_json_keys` | array | Extra structured-output keys. |
| `disable_reply` | boolean | Stop sending replies. |
| `analyze_images` | boolean | Read images sent by the contact. |
| `enable_message_burst_handling` | boolean | Group rapid incoming messages. |
| `can_send_images` | boolean | Allow sending images. |
| `can_send_audio` | boolean | Allow sending audio. |
| `can_send_video` | boolean | Allow sending video. |
| `can_send_documents` | boolean | Allow sending documents. |
| `response_config` | object \| null | Single or multi-message replies. |
| `agent_loop_config` | object \| null | Tool-calling loop limits. |
| `ai_safeguards` | object \| null | Safeguard overrides. |
| `schedule_config` | object \| null | Availability schedule. |
| `internal_tools` | object \| null | AchieveApex actions the assistant may use. |
| `api_tools` | array \| null | Associated [API tools](#api-tools). |
| `mcp_tools` | array \| null | Connected [MCP servers](#mcp-tool-connections). |
| `telnyx_ai_assistant_config` | object \| null | Voice configuration. See [Configure a voice assistant](#ai-assistants--voice). |
| `acting_user_id` | integer \| null | Voice only: user identity for write actions. |

Every update generates a new `version_id` and, for voice assistants, re-syncs the voice agent with the voice provider. Updates made with an API key are not recorded in the [change history](#ai-assistants--history).

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistants/123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Concierge",
    "ai_model_id": 8,
    "timezone": "America/New_York"
  }'
```

#### Response

The updated [AI assistant object](#ai-assistants), including the read-only `ai_safeguards_system` object (shortened):

```json
{
  "id": 123,
  "organization_id": 27,
  "name": "Support Concierge",
  "assistant_type": "conversation",
  "ai_model_id": 8,
  "connection": "system",
  "timezone": "America/New_York",
  "version_id": "5e2f7a10-3c4d-4b6e-9f8a-7b6c5d4e3f2a",
  "updated_at": "2026-04-25T15:30:00.000Z"
}
```

#### Instructions and guided mode

Advanced mode: write `instructions` yourself.

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistants/123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions_language": "ENG",
    "is_easy_mode": false,
    "easy_mode_config": null,
    "instructions": "You are a helpful support assistant. Answer only using verified company information."
  }'
```

Guided mode stores the structured `easy_mode_config` and the prompt generated from it in `instructions`. The server does not generate the prompt for you: send both.

```json
{
  "instructions_language": "ENG",
  "is_easy_mode": true,
  "easy_mode_config": {
    "brand": "Apex Hotels",
    "assistantName": "Ava",
    "role": "hotel reservation assistant",
    "objectives": [{ "id": "1", "value": "Help guests understand room availability and amenities." }],
    "restrictions": [{ "id": "1", "value": "Do not promise discounts that are not listed." }],
    "additionalInstructions": [],
    "products": [{ "id": "room-deluxe", "name": "Deluxe Room", "price": "$180/night", "description": "King bed, city view" }],
    "promotions": [],
    "conversationFlows": [],
    "companyLocations": [],
    "dialectSections": [],
    "dynamicSections": []
  },
  "instructions": "## Your identity\nYou work for Apex Hotels..."
}
```

#### Human handoff

`human_handoff_config.rules[]` define when the assistant hands the conversation (or call) to people.

```json
{
  "human_handoff_config": {
    "rules": [
      {
        "name": "billing",
        "instructions": "Use this rule when the customer asks for refunds, invoices, or payment disputes.",
        "team_members": [
          { "user_id": 45, "weight": 70 },
          { "user_id": 46, "weight": 30 }
        ],
        "handoff_message": "I am transferring you to our billing team.",
        "keep_assigned_team_member": false,
        "assign_to_contact_owner": false,
        "unassign_ai_agent": true,
        "mark_conversation_unread": true,
        "pipeline_id": 12,
        "stage_id": 34,
        "respect_advisor_availability": true,
        "availability_fallback": { "type": "fallback_user", "user_id": 47 }
      }
    ]
  }
}
```

| Rule field | Type | Description |
|---|---|---|
| `name` | string | Required. 1-10 lowercase letters, numbers or underscores, unique per assistant. |
| `instructions` | string | Required. When to use this rule. |
| `team_members` | array | Required. `{ user_id, weight }`; users must be members of your organization and weights must add up to 100. For voice assistants each user must be an active voice agent. Can be empty only when `assign_to_contact_owner` is `true`. |
| `handoff_message` | string \| null | Message sent when handing off. |
| `keep_assigned_team_member` | boolean \| null | Keep the currently assigned person. |
| `assign_to_contact_owner` | boolean \| null | Assign to the contact owner. |
| `unassign_ai_agent` | boolean \| null | Remove the assistant from the conversation. |
| `mark_conversation_unread` | boolean \| null | Mark the conversation unread. |
| `pipeline_id` / `stage_id` | integer \| null | Move the related deal to this pipeline stage. |
| `respect_advisor_availability` | boolean \| null | Only assign to available advisors. Requires `availability_fallback.type`. |
| `availability_fallback` | object \| null | `type`: `unassigned`, `keep_ai`, `fallback_user` (requires `user_id` of a member) or `contact_owner`. |

#### AI assistant handoff

`ai_assistant_handoff_config.rules[]` hand the conversation to another assistant of your organization. A voice assistant can only hand off to voice assistants and vice versa, and never to itself.

```json
{
  "ai_assistant_handoff_config": {
    "rules": [
      {
        "name": "Technical support specialist",
        "instructions": "Use this rule when the user needs troubleshooting steps.",
        "ai_assistant_id": 124,
        "handoff_message": "I am connecting you with our technical support assistant.",
        "keep_assigned_human": false,
        "mark_conversation_unread": false,
        "trigger_ai_reply": true,
        "also_send_current_ai_reply": false
      }
    ]
  }
}
```

`name`, `instructions` and `ai_assistant_id` are required. `trigger_ai_reply` makes the target assistant reply right away; `also_send_current_ai_reply` also sends the current assistant's reply.

#### Follow-up rules

```json
{
  "follow_up_config": {
    "enabled": true,
    "follow_up_limit": 3,
    "rules": [
      {
        "id": "Rule-1",
        "when_to_assign": "The customer asked for pricing but did not answer after the assistant reply.",
        "time_after": 1440,
        "follow_up_actions": [
          { "type": "ai_generated_message", "instruction": "Send a short friendly reminder about pricing." },
          { "type": "template", "template": { "type": "whatsapp", "template_id": 55 } },
          { "type": "automation", "automation_id": 987 }
        ]
      }
    ]
  }
}
```

Each rule requires `id`, `when_to_assign` and `follow_up_actions`. Action `type` is `template` (with `template.type` `email`, `whatsapp` or `predefined_message` and `template.template_id`), `automation` (`automation_id`) or `ai_generated_message` (`instruction`).

#### Automations and entity access

```json
{
  "access_permissions_automations": [
    {
      "automation_id": 987,
      "when_to_use": "Create a billing follow-up task when a customer requests an invoice.",
      "default_response": "I created the billing follow-up task.",
      "wait_for_response": true
    }
  ],
  "access_permissions_contact": "read_write",
  "access_permissions_deals": "read",
  "access_permissions_customer_support": "none"
}
```

`automation_id` and `when_to_use` are required. `wait_for_response` waits for the automation result; `default_response` is used otherwise.

#### Advanced options

```json
{
  "advanced_options": {
    "verbosity": "low",
    "reasoning_effort": "none",
    "persist_tool_context": true,
    "tools": {
      "search_product": true,
      "web_search": true,
      "web_search_config": {
        "user_location": { "type": "approximate", "country": "US", "city": "New York", "region": "NY", "timezone": "America/New_York" },
        "allowed_domains": ["example.com"]
      }
    },
    "conversation_summary_config": {
      "enabled": true,
      "instructions": "Summarize customer intent, promised next steps, and important account details."
    }
  },
  "disable_reply": false,
  "analyze_images": true,
  "enable_message_burst_handling": true,
  "can_send_images": true,
  "can_send_audio": false,
  "can_send_video": false,
  "can_send_documents": true,
  "response_config": {
    "response_mode": "multi",
    "max_messages_per_response": 3,
    "delay_between_messages_ms": 1000,
    "allow_no_reply": true,
    "no_reply_instructions": "Do not reply to messages that only say thanks."
  },
  "agent_loop_config": { "max_iterations": 20, "enable_clarification": true },
  "additional_json_keys": [
    { "key": "customer_priority", "type": "string", "description": "Priority detected from the conversation", "required": false }
  ]
}
```

`web_search_config.user_location.country` is a 2-letter code and `allowed_domains` holds up to 20 domains. `persist_tool_context` keeps previous tool results in the conversation context.

#### AI safeguards

`ai_safeguards` overrides the protection that stops an assistant from looping or replying too fast. Omit a key (or set it to `null`) to use the system value; out-of-range values are clamped. [Get the assistant](#ai-assistants--get) to see the current system defaults in `ai_safeguards_system`.

| Key | Type | Range |
|---|---|---|
| `max_executions_per_hour` | integer | 20-200 |
| `max_executions_per_day` | integer | 50-1000 |
| `max_responses_per_minute` | integer | 2-30 |
| `min_response_time_seconds` | number | 0-10 |
| `max_tokens_per_minute` | integer | 50000-2000000 |
| `anomaly_detection_enabled` | boolean | |
| `lookback_minutes` | integer | 5-60 |
| `min_total_messages` | integer | 10-300 |
| `min_ai_outgoing_messages` | integer | 5-150 |
| `min_active_minutes` | integer | 1-60 |
| `min_alternation_ratio` | number | 0.3-1 |
| `alternation_burst_window_ms` | integer | 0-10000 |
| `max_human_agent_messages` | integer | 0-50 |
| `min_repeated_incoming_text_count` | integer | 0-100 |
| `strong_repeated_incoming_text_count` | integer | 0-200 |
| `min_unsupported_incoming_messages` | integer | 0-100 |
| `require_secondary_signal` | boolean | |
| `ignored_repeated_incoming_texts` | string[] | up to 50 texts of 60 characters |

```json
{ "ai_safeguards": { "max_responses_per_minute": 10, "anomaly_detection_enabled": true } }
```

#### Schedule

```json
{
  "schedule_config": {
    "always_on": false,
    "out_of_schedule_action": "handoff",
    "schedule_not_available_message": "Our team is offline. We will follow up during business hours.",
    "weekly_schedule": {
      "monday": [{ "start_time": "09:00", "end_time": "17:00" }],
      "tuesday": [{ "start_time": "09:00", "end_time": "17:00" }],
      "wednesday": [{ "start_time": "09:00", "end_time": "17:00" }],
      "thursday": [{ "start_time": "09:00", "end_time": "17:00" }],
      "friday": [{ "start_time": "09:00", "end_time": "17:00" }],
      "saturday": [],
      "sunday": []
    },
    "schedule_handoff_config": {
      "handoff_message": "I am transferring you to the available team.",
      "unassign_ai_agent": true,
      "mark_conversation_unread": true,
      "team_members": [{ "user_id": 45, "weight": 100 }],
      "per_day_distribution": { "saturday": [{ "user_id": 46, "weight": 100 }] },
      "respect_advisor_availability": false
    }
  }
}
```

`out_of_schedule_action` is `message` (default) or `handoff`. `schedule_handoff_config` also accepts `availability_fallback` with the same shape as in human handoff rules.

#### Internal tools

```json
{
  "internal_tools": {
    "enabled": true,
    "tools": {
      "find_contact": true,
      "get_contact": true,
      "update_contact": true,
      "find_deals": true,
      "create_activity": true,
      "send_conversation_message": true,
      "execute_automation": true,
      "search_products": true,
      "track_conversation_event": true
    },
    "track_conversation_event_config": { "event_definition_ids": [3, 7] }
  }
}
```

Common tool keys:

| Category | Tool keys |
|---|---|
| CRM | `create_contact`, `find_contact`, `get_contact`, `update_contact`, `set_contact_dnd`, `create_deal`, `find_deals`, `get_deal`, `update_deal`, `add_deal_products`, `create_company`, `find_company`, `get_company`, `update_company`, `add_note`, `update_note`, `create_activity`, `update_activity`, `delete_activity`, `get_pipelines`, `get_currencies`, `get_custom_fields` |
| Help desk | `create_helpdesk_ticket`, `get_helpdesk_ticket`, `find_helpdesk_tickets`, `search_helpdesk_knowledge` |
| Messaging | `find_conversations`, `get_conversation`, `update_conversation`, `get_conversation_messages`, `search_conversation_messages`, `initiate_whatsapp_conversation`, `find_whatsapp_template`, `send_whatsapp_template`, `send_conversation_message`, `get_email_broadcast_senders`, `send_email_broadcast`, `track_conversation_event` |
| Products and orders | `get_product`, `search_products`, `find_orders`, `get_order`, `create_order`, `update_order`, `add_order_item`, `update_order_item`, `delete_order_item`, `cancel_order`, `get_order_payment_link`, `update_order_fulfillment`, `convert_estimate_to_order`, `convert_order_to_invoice`, `create_checkout_link` |
| Billing and finance | `get_estimate_pdf`, `get_invoice_pdf`, `find_finance_plans`, `get_finance_plan`, `calculate_finance_scenario`, `create_finance_plan`, `update_finance_plan`, `save_finance_plan_version` |
| Loyalty and links | `list_loyalty_programs`, `get_loyalty_card`, `enroll_loyalty_member`, `redeem_loyalty_reward`, `create_smart_link` |
| Voices | `get_organization_ai_voices`, `synthesize_ai_voice` |
| Automations | `find_automations`, `execute_automation` |
| Reservations | `find_reservations`, `create_reservation`, `update_reservation`, `delete_reservation`, `get_reservation_services` |

#### API tool associations

Create the tool with the [API Tools API](#api-tools), then attach it:

```json
{
  "api_tools": [
    {
      "api_tool_id": 77,
      "description": "Lookup shipment status",
      "when_to_use": "Use when the customer asks where their package is.",
      "config": null
    }
  ]
}
```

`api_tool_id` is required.

#### MCP servers

Check the server with the [MCP connection test](#mcp-tool-connections--test), then store it:

```json
{
  "mcp_tools": [
    {
      "url": "https://mcp.example.com/v1",
      "label": "Knowledge MCP",
      "description": "Company knowledge tools",
      "authentication_type": "api_key",
      "api_key": "mcp_live_key",
      "enabled_tools": ["search_docs"],
      "tools": [
        {
          "name": "search_docs",
          "description": "Search company documentation",
          "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] }
        }
      ]
    }
  ]
}
```

#### Errors

| Status | When |
|---|---|
| `400` | Invalid value, unknown top-level field, invalid human handoff rule, schedule handoff or external handoff target. |
| `404` | The assistant does not exist, is deleted or belongs to another organization. |
| `500` | An AI assistant handoff rule points to a missing assistant, the wrong assistant type, or the assistant itself (the message explains which). |

<a id="ai-assistants--delete"></a>

### Delete an AI assistant

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/delete

Delete an AI assistant.

#### Endpoint

`DELETE /ai-assistants/:id`

This is a soft delete: the assistant gets a `deleted_at` timestamp and no longer appears in list or get. Conversations currently assigned to the assistant are unassigned from it (their handoff reason is set to "AI Assistant was deleted").

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/ai-assistants/123 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [AI assistant object](#ai-assistants), with `deleted_at` set.

```json
{
  "id": 123,
  "name": "Sales Concierge",
  "organization_id": 27,
  "deleted_at": "2026-04-25T12:30:00.000Z"
}
```

#### Duplicate instead of deleting

There is no duplicate endpoint. To copy an assistant, [get it](#ai-assistants--get), remove `id`, `version_id`, `created_by_user_id`, `created_at`, `updated_at`, `deleted_at` and `ai_safeguards_system`, change `name`, and [create](#ai-assistants--create) a new one.

<a id="ai-assistants--voice"></a>

### Configure a voice assistant

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/voice

Voice assistants (`assistant_type: "voice"`) keep their runtime settings in `telnyx_ai_assistant_config`. You change them with a normal assistant update; after every create or update the voice agent is synced with the voice provider.

#### Endpoint

`PATCH /ai-assistants/:id`

Use the catalog endpoints to pick valid values: [voice LLM models](#ai-assistants--voice-models), [voices](#ai-assistants--voice-voices) and [transcription languages](#ai-assistants--voice-transcription-languages).

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistants/501 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acting_user_id": 93,
    "telnyx_ai_assistant_config": {
      "sync_status": "pending",
      "voice_runtime": "telnyx_builtin",
      "use_custom_llm": false,
      "model": "openai/gpt-4.1",
      "greeting": "Hi, thanks for calling Achieve Apex. How can I help?",
      "voice_provider": "telnyx",
      "voice_provider_model": "Ultra",
      "voice_id": "voice_abc123",
      "voice_name": "Allison",
      "voice_model": "telnyx.Ultra.voice_abc123",
      "voice_speed": 1,
      "voice_language_boost": "English",
      "voice_expressive_mode": true,
      "background_audio": { "type": "predefined_media", "value": "office" },
      "transcription_model": "deepgram/nova-3",
      "transcription_language": "auto",
      "speaking_wait_seconds": 0.4,
      "speaking_on_punctuation_seconds": 0.2,
      "speaking_on_no_punctuation_seconds": 1.2,
      "speaking_on_number_seconds": 0.5,
      "interruption_enable": true,
      "widget_settings": {
        "theme": "dark",
        "position": "fixed",
        "default_state": "closed",
        "start_call_text": "Start call",
        "agent_thinking_text": "Thinking...",
        "speak_to_interrupt_text": "Speak to interrupt"
      }
    }
  }'
```

`telnyx_ai_assistant_config` is replaced as a whole: send the full object (get the assistant first and change what you need).

#### Response

The updated [AI assistant object](#ai-assistants) (shortened):

```json
{
  "id": 501,
  "assistant_type": "voice",
  "voice_enabled": true,
  "acting_user_id": 93,
  "telnyx_ai_assistant_config": {
    "telnyx_assistant_id": "assistant-6c0e...",
    "sync_status": "synced",
    "voice_runtime": "telnyx_builtin",
    "model": "openai/gpt-4.1",
    "greeting": "Hi, thanks for calling Achieve Apex. How can I help?",
    "voice_model": "telnyx.Ultra.voice_abc123"
  },
  "updated_at": "2026-04-25T16:00:00.000Z"
}
```

#### Voice configuration fields

| Field | Type | Description |
|---|---|---|
| `acting_user_id` | integer \| null | User whose identity the assistant uses for write actions during calls. |
| `telnyx_ai_assistant_config.telnyx_assistant_id` | string \| null | Read-only in practice. ID of the synced voice agent at the provider. |
| `telnyx_ai_assistant_config.sync_status` | string \| null | `pending`, `synced` or `error`. Send `pending` when you change settings. |
| `telnyx_ai_assistant_config.last_synced_at` | string (date-time) \| null | Read-only. Last successful sync. |
| `telnyx_ai_assistant_config.error_message` | string \| null | Read-only. Last sync error. |
| `telnyx_ai_assistant_config.voice_runtime` | string \| null | `telnyx_builtin`, `custom_llm` or `openai_realtime_sip`. |
| `telnyx_ai_assistant_config.model` | string \| null | LLM for the `telnyx_builtin` runtime, from [voice LLM models](#ai-assistants--voice-models). |
| `telnyx_ai_assistant_config.use_custom_llm` | boolean \| null | Whether the custom LLM runtime is used. |
| `telnyx_ai_assistant_config.custom_llm_model` | string \| null | Model used by the custom LLM runtime. |
| `telnyx_ai_assistant_config.openai_realtime_model` | string \| null | Model for the `openai_realtime_sip` runtime. |
| `telnyx_ai_assistant_config.openai_realtime_voice` | string \| null | Voice for the `openai_realtime_sip` runtime. |
| `telnyx_ai_assistant_config.greeting` | string \| null | First sentence spoken on the call. |
| `telnyx_ai_assistant_config.description` | string \| null | Description sent to the voice provider. |
| `telnyx_ai_assistant_config.voice_mode` | string \| null | `unified` or `distinct`. |
| `telnyx_ai_assistant_config.voice_provider` | string \| null | TTS provider ID from the [voices catalog](#ai-assistants--voice-voices) (`telnyx`, `aws`, `azure`, `elevenlabs`, `minimax`, ...). Lowercase letters, numbers, `_` and `-`. |
| `telnyx_ai_assistant_config.voice_provider_model` | string \| null | Provider voice model. |
| `telnyx_ai_assistant_config.voice_id` | string \| null | Provider voice ID. |
| `telnyx_ai_assistant_config.voice_name` | string \| null | Display name of the voice. |
| `telnyx_ai_assistant_config.voice_model` | string \| null | Full voice identifier, e.g. `telnyx.Ultra.voice_abc123`. |
| `telnyx_ai_assistant_config.voice_api_key` | string | Write-only. Provider key for bring-your-own-key providers (`elevenlabs`, `rime`, `resemble`). It is stored as a secret and replaced by `voice_api_key_ref`; it is never saved on the assistant. |
| `telnyx_ai_assistant_config.voice_api_key_ref` | string \| null | Reference to the stored provider key. |
| `telnyx_ai_assistant_config.voice_speed` | number \| null | Speech speed multiplier. |
| `telnyx_ai_assistant_config.voice_language_boost` | string \| null | Language boost for supported voices (values in the voices catalog `language_boost_values`). |
| `telnyx_ai_assistant_config.voice_expressive_mode` | boolean \| null | Expressive mode for supported voices. |
| `telnyx_ai_assistant_config.voice_similarity_boost` | number \| null | ElevenLabs similarity boost. |
| `telnyx_ai_assistant_config.voice_style` | number \| null | ElevenLabs style. |
| `telnyx_ai_assistant_config.voice_use_speaker_boost` | boolean \| null | ElevenLabs speaker boost. |
| `telnyx_ai_assistant_config.background_audio` | object \| null | `type` (`predefined_media`, `media_url` or `media_name`) and `value`. |
| `telnyx_ai_assistant_config.transcription_model` | string \| null | Speech-to-text model, e.g. `deepgram/nova-3`. |
| `telnyx_ai_assistant_config.transcription_language` | string \| null | Language code or `auto`, from [transcription languages](#ai-assistants--voice-transcription-languages). |
| `telnyx_ai_assistant_config.transcription_region` | string \| null | Transcription region. |
| `telnyx_ai_assistant_config.transcription_settings` | object \| null | Model tuning: `eot_threshold` (0.5-0.9), `eot_timeout_ms` (500-10000), `eager_eot_threshold` (0.3-0.9), `keyterm` (max 1000 chars), `context` (max 10000 chars). |
| `telnyx_ai_assistant_config.interruption_enable` | boolean \| null | Callers can interrupt the assistant. |
| `telnyx_ai_assistant_config.speaking_wait_seconds` | number \| null | Wait before speaking. |
| `telnyx_ai_assistant_config.speaking_on_punctuation_seconds` | number \| null | Wait after punctuation. |
| `telnyx_ai_assistant_config.speaking_on_no_punctuation_seconds` | number \| null | Wait when there is no punctuation. |
| `telnyx_ai_assistant_config.speaking_on_number_seconds` | number \| null | Wait after numbers. |
| `telnyx_ai_assistant_config.enabled_tools` | string[] \| null | Voice tools enabled on the agent. |
| `telnyx_ai_assistant_config.hangup_tool_description` | string \| null | When the assistant should hang up. |
| `telnyx_ai_assistant_config.dynamic_variables_enabled` | boolean \| null | Enable dynamic variables in the prompt. |
| `telnyx_ai_assistant_config.dynamic_variables_defaults` | object \| null | Default values of dynamic variables. |
| `telnyx_ai_assistant_config.dynamic_variables_automation_id` | integer \| null | Automation that resolves dynamic variables at call start. |
| `telnyx_ai_assistant_config.dynamic_variables_webhook_enabled` | boolean \| null | Resolve dynamic variables from your webhook. |
| `telnyx_ai_assistant_config.dynamic_variables_webhook_url` | string \| null | Your dynamic variables webhook URL. |
| `telnyx_ai_assistant_config.post_conversation_enabled` | boolean \| null | Run post-call analysis. |
| `telnyx_ai_assistant_config.post_conversation_instructions` | string \| null | Instructions for the post-call analysis. |
| `telnyx_ai_assistant_config.supports_unauthenticated_web_calls` | boolean \| null | Allow calls from the public web widget. |
| `telnyx_ai_assistant_config.widget_settings` | object \| null | Web widget appearance. |
| `telnyx_ai_assistant_config.data_retention` | boolean \| null | Provider data retention. |
| `telnyx_ai_assistant_config.transfer_from_number` | string \| null | Company number used as caller ID for external transfers. |
| `telnyx_ai_assistant_config.external_transfer_caller_id_mode` | string \| null | `company_number` or `original_caller`. |

Other keys in `telnyx_ai_assistant_config` (`webhook_url`, `delivery_status_webhook_url`, `enabled_features`, `telnyx_tools`, `knowledge_*`, `elevenlabs_agent_id`, `imported_from`, `openai_realtime_sip_uri`, `debug_webhook_base_url`) are maintained by the platform during sync; keep the values you read.

#### Background audio

```json
{ "background_audio": { "type": "predefined_media", "value": "office" } }
```

| Type | Value |
|---|---|
| `predefined_media` | A predefined sound, e.g. `silence` or `office`. |
| `media_url` | A public audio URL. |
| `media_name` | The name of an uploaded media file. |

#### Web widget

```json
{
  "widget_settings": {
    "theme": "light",
    "position": "fixed",
    "default_state": "closed",
    "logo_icon_url": "https://cdn.example.com/logo.png",
    "start_call_text": "Start call",
    "agent_thinking_text": "Thinking...",
    "speak_to_interrupt_text": "Speak to interrupt"
  }
}
```

When the assistant has a `telnyx_assistant_id`, embed it on your site:

```html
<telnyx-ai-agent agent-id="TELNYX_ASSISTANT_ID"></telnyx-ai-agent>
<script async src="https://unpkg.com/@telnyx/ai-agent-widget"></script>
```

#### External call transfers

Voice assistants can transfer calls to external numbers or SIP URIs with `external_handoff_targets` (only allowed on voice assistants).

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistants/501 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_handoff_targets": {
      "rules": [
        {
          "id": "external-target-sales-co",
          "name": "Colombia Sales Line",
          "label": "Sales Colombia",
          "instructions": "Use this destination when callers ask for sales in Colombia.",
          "destination_type": "external_number",
          "phone_number": "+5715550101",
          "country_code": "CO",
          "handoff_message": "I will connect you with our Colombia sales team.",
          "timeout_secs": 30,
          "enabled": true
        }
      ]
    }
  }'
```

| Rule field | Type | Description |
|---|---|---|
| `id` | string | Required. Unique per assistant. |
| `name` | string | Required. |
| `label` | string | Required. Unique per assistant. |
| `instructions` | string | Required. When to transfer. |
| `destination_type` | string | Required. `external_number` or `sip_uri`. |
| `phone_number` | string \| null | E.164 number for `external_number`. |
| `sip_uri` | string \| null | SIP URI for `sip_uri`. |
| `country_code` | string \| null | 2-letter country code. |
| `handoff_message` | string \| null | Spoken before transferring. |
| `timeout_secs` | number \| null | 5-120. |
| `enabled` | boolean \| null | Whether the target is active. |

Destinations must be unique. Set `telnyx_ai_assistant_config.external_transfer_caller_id_mode` and `transfer_from_number` to control the caller ID.

#### Refresh from the voice provider

To pull changes made directly at the voice provider, get the assistant with `$syncFromTelnyx=true` (see [Get an AI assistant](#ai-assistants--get)).

<a id="ai-assistants--history-get"></a>

### Get a history entry

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/history-get

Retrieve one configuration snapshot by ID. See [List configuration history](#ai-assistants--history) for the fields.

#### Endpoint

`GET /ai-assistants-change-history/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/ai-assistants-change-history/9001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 9001,
  "organization_id": 27,
  "ai_assistant_id": 123,
  "created_by_user_id": 45,
  "created_by_user": { "id": 45, "email": "admin@example.com", "first_name": "Jane", "last_name": "Admin", "avatar_url": null },
  "configuration": {
    "id": 123,
    "name": "Sales Assistant",
    "instructions": "You are a sales assistant...",
    "instructions_language": "ENG"
  },
  "created_at": "2026-04-25T19:30:00.000Z",
  "updated_at": "2026-04-25T19:30:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404` | The entry does not exist or belongs to another organization. |

<a id="ai-assistants--history"></a>

### List configuration history

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/history

Every time a team member creates or updates an assistant in the app, a snapshot of the full configuration is saved. List those snapshots to inspect previous versions or to find what was active at a given time. Changes made with an API key are not recorded.

#### Endpoint

`GET /ai-assistants-change-history`

#### The history entry object

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. Use it to [restore](#ai-assistants--restore). |
| `organization_id` | integer | Read-only. Organization of the assistant. |
| `ai_assistant_id` | integer | Read-only. Assistant this snapshot belongs to. |
| `created_by_user_id` | integer | Read-only. User who made the change. |
| `configuration` | object | Read-only. Full [AI assistant object](#ai-assistants) as saved by that change. |
| `created_by_user` | object \| null | Read-only. `id`, `email`, `first_name`, `last_name`, `avatar_url` of the user. |
| `created_at` | string (date-time) | Read-only. When the change was made. |
| `updated_at` | string (date-time) | Read-only. Last update timestamp. |
| `deleted_at` | string (date-time) \| null | Read-only. Always `null` in results. |

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ai_assistant_id` | integer | No | Snapshots of one assistant. |
| `created_by_user_id` | integer | No | Snapshots made by one user. |
| `created_at[$lte]` | string (date-time) | No | Snapshots made on or before this time (also `$lt`, `$gte`, `$gt`). |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[created_at]` | integer | No | `-1` for newest first. |

Results are limited to your API key's organization.

#### Request

```bash
curl -G https://integrations.achieveapex.com/ai-assistants-change-history \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'ai_assistant_id=123' \
  --data-urlencode '$sort[created_at]=-1' \
  --data-urlencode '$limit=20'
```

Configuration that was active when a message was sent (latest snapshot before that time):

```bash
curl -G https://integrations.achieveapex.com/ai-assistants-change-history \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'ai_assistant_id=123' \
  --data-urlencode 'created_at[$lte]=2026-04-25T19:00:00.000Z' \
  --data-urlencode '$sort[created_at]=-1' \
  --data-urlencode '$limit=1'
```

#### Response

```json
{
  "total": 2,
  "limit": 20,
  "skip": 0,
  "data": [
    {
      "id": 9001,
      "organization_id": 27,
      "ai_assistant_id": 123,
      "created_by_user_id": 45,
      "created_at": "2026-04-25T19:30:00.000Z",
      "updated_at": "2026-04-25T19:30:00.000Z",
      "deleted_at": null,
      "created_by_user": {
        "id": 45,
        "email": "admin@example.com",
        "first_name": "Jane",
        "last_name": "Admin",
        "avatar_url": null
      },
      "configuration": {
        "id": 123,
        "name": "Sales Assistant",
        "organization_id": 27,
        "assistant_type": "conversation",
        "instructions": "You are a sales assistant...",
        "instructions_language": "ENG",
        "ai_model_id": 8
      }
    }
  ]
}
```

<a id="ai-assistants--voice-transcription-languages"></a>

### List transcription languages

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/voice-transcription-languages

List the languages a speech-to-text model accepts, for `telnyx_ai_assistant_config.transcription_language`.

#### Endpoint

`GET /telnyx-ai-transcription-languages`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `transcription_model` | string | No | Speech-to-text model, e.g. `deepgram/nova-3`. Default `deepgram/nova-3`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/telnyx-ai-transcription-languages \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'transcription_model=deepgram/nova-3'
```

#### Response

```json
{
  "total": 3,
  "limit": 3,
  "skip": 0,
  "transcription_model": "deepgram/nova-3",
  "data": [
    { "value": "auto", "label": "Auto" },
    { "value": "en", "label": "English" },
    { "value": "es", "label": "Spanish" }
  ]
}
```

Store `data[].value` in `transcription_language`. `auto` lets the model detect the language.

<a id="ai-assistants--voice-models"></a>

### List voice LLM models

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/voice-models

List the language models a voice assistant can use with the `telnyx_builtin` runtime (`telnyx_ai_assistant_config.model`). The catalog is read live from the voice provider and cached for 30 minutes; it is the same for every organization.

#### Endpoint

`GET /telnyx-ai-models`

#### Query parameters

None. The whole catalog is returned in one page.

#### Request

```bash
curl https://integrations.achieveapex.com/telnyx-ai-models \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "total": 2,
  "limit": 2,
  "skip": 0,
  "default_model": "moonshotai/Kimi-K2.6",
  "source": "telnyx",
  "data": [
    {
      "id": "moonshotai/Kimi-K2.6",
      "owned_by": "Telnyx",
      "organization": null,
      "task": "text-generation",
      "hosted_by_telnyx": true,
      "recommended_for_assistants": true,
      "is_default": true,
      "beta": false,
      "description": null,
      "context_length": 131072,
      "tier": null,
      "pricing": { "input": 0.6, "output": 2.5, "cached_prompt": null, "currency": "USD", "unit": "1M_tokens" }
    },
    {
      "id": "openai/gpt-4.1",
      "owned_by": "openai",
      "organization": null,
      "task": "text generation",
      "hosted_by_telnyx": false,
      "recommended_for_assistants": true,
      "is_default": false,
      "beta": false,
      "description": null,
      "context_length": null,
      "tier": null,
      "pricing": null
    }
  ]
}
```

| Field | Description |
|---|---|
| `default_model` | Model used when none is set. |
| `source` | `telnyx` when read from the provider, `fallback` when the provider could not be reached and a short built-in list is returned. |
| `data[].id` | Value to store in `telnyx_ai_assistant_config.model`. |
| `data[].hosted_by_telnyx` | Model runs on the voice provider's infrastructure. |
| `data[].recommended_for_assistants` | Recommended for voice assistants. |
| `data[].pricing` | Provider list price per `unit`, or `null`. |

<a id="ai-assistants--voice-voices"></a>

### List voices

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/voice-voices

List the text-to-speech voices and providers available to voice assistants. Use a voice's `provider`, `model_id`, `voice_id` and `id` to fill `voice_provider`, `voice_provider_model`, `voice_id` and `voice_model` in `telnyx_ai_assistant_config`. The catalog is read from the voice provider and cached for 30 minutes; it is the same for every organization.

#### Endpoint

`GET /telnyx-ai-voices`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `provider` | string | No | Only voices of this provider, e.g. `telnyx`, `aws`, `azure`, `minimax`, `elevenlabs`. |
| `api_key_ref` | string | No | For bring-your-own-key providers (`elevenlabs`, `rime`): the `voice_api_key_ref` stored on one of your assistants, so the account's own voices are listed. |
| `providers_only` | boolean | No | `true` returns only `providers` and `language_boost_values`, with an empty `data`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/telnyx-ai-voices \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'provider=telnyx'
```

Voices of a bring-your-own-key provider already configured on an assistant:

```bash
curl -G https://integrations.achieveapex.com/telnyx-ai-voices \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'provider=elevenlabs' \
  --data-urlencode 'api_key_ref=YOUR_VOICE_API_KEY_REF'
```

To list the voices of a provider key that is not stored yet, send it in a JSON body with `POST /telnyx-ai-voices` (`provider` and `api_key`). The key is only used for this lookup. To keep it, send it as `telnyx_ai_assistant_config.voice_api_key` when you [update the assistant](#ai-assistants--voice).

```bash
curl -X POST https://integrations.achieveapex.com/telnyx-ai-voices \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "elevenlabs", "api_key": "ELEVENLABS_API_KEY" }'
```

#### Response

```json
{
  "total": 1,
  "limit": 1,
  "skip": 0,
  "data": [
    {
      "id": "Telnyx.NaturalHD.astra",
      "voice_id": "Telnyx.NaturalHD.astra",
      "name": "Astra",
      "provider": "telnyx",
      "model_id": "NaturalHD",
      "language": "en-US",
      "languages": null,
      "gender": "female",
      "accent": null,
      "age": null,
      "description": null,
      "deprecated": false
    }
  ],
  "providers": [
    { "id": "telnyx", "label": "Telnyx", "requires_api_key": false, "accepts_api_key": false, "voice_count": 120, "models": ["NaturalHD"] },
    { "id": "elevenlabs", "label": "ElevenLabs", "requires_api_key": true, "accepts_api_key": true, "voice_count": 0, "models": [] }
  ],
  "language_boost_values": ["English", "Spanish"]
}
```

| Field | Description |
|---|---|
| `providers[].requires_api_key` | The provider only lists and speaks voices with your own provider key. |
| `providers[].accepts_api_key` | The provider can use your own key (stored with `voice_api_key`). |
| `language_boost_values` | Accepted values of `voice_language_boost`. |

#### Errors

| Status | When |
|---|---|
| `400` | The provider rejected the request (for example an invalid provider key). The body has the usual shape with an empty `data` and an `error` message. |

<a id="ai-assistants--restore"></a>

### Restore a configuration version

Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/restore

Restore an assistant from a [history entry](#ai-assistants--history), either only its instructions or its main configuration. The assistant is updated in place; the restore itself is not recorded as a new history entry.

#### Endpoint

`POST /ai-assistants-restore-from-changes-history`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `history_id` | integer | Yes | ID of the history entry to restore. |
| `restore_type` | string | Yes | `instructions` or `all`. |

- `instructions` restores `instructions` and `instructions_language`.
- `all` restores `name`, `description`, `instructions`, `instructions_language`, `connection`, `specific_openai_secret_key`, `ai_model_id`, `advanced_options`, `access_permissions_contact`, `access_permissions_deals`, `access_permissions_customer_support`, `access_permissions_automations`, `human_handoff_config`, `external_handoff_targets` and `additional_json_keys`. Other fields (tools, schedule, follow-ups, voice settings, ...) are left as they are.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/ai-assistants-restore-from-changes-history \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "history_id": 9001,
    "restore_type": "instructions"
  }'
```

#### Response

```json
{
  "success": true,
  "message": "Instructions restored successfully",
  "assistant_id": 123
}
```

With `restore_type: "all"` the message is `Configuration restored successfully`.

#### Errors

| Status | When |
|---|---|
| `403` | The assistant belongs to another organization. |
| `404` | The history entry does not exist. |
| `500` | `restore_type` is not `instructions` or `all` (message `Invalid restore type`). |

---

## AI Models

<a id="ai-models"></a>

### AI Models overview

Source: https://www.achieveapex.com/docs/api-reference/ai-models

The AI model catalog lists the language models an AI assistant can run on. It is global and read-only: use a model's `id` as `ai_model_id` when you create or update an [AI assistant](#ai-assistants).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/ai-models` | [List AI models](#ai-models--list) |
| `GET` | `/ai-models/:id` | [Get an AI model](#ai-models--get) |

The catalog is the same for every organization. Creating, changing or deleting models is reserved to AchieveApex administrators.

#### The AI model object

```json
{
  "id": 12,
  "provider": "openrouter",
  "model_name": "openai/gpt-4.1",
  "label": "GPT-4.1",
  "small_description": "General purpose model with long context",
  "intelligence": 4,
  "reasoning": 3,
  "cost": 3,
  "speed": 4,
  "input_price_per_1m_tokens": 3.5,
  "output_price_per_1m_tokens": 14,
  "status": "visible",
  "active_in_conversations": true,
  "active_in_tickets": true,
  "active_in_ai_chat": true,
  "active_in_voice": false,
  "provider_metadata": {
    "context_length": 1047576,
    "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["text"] }
  },
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-04-02T09:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Use it as `ai_model_id` on assistants. |
| `provider` | string | `openai` or `openrouter`. |
| `model_name` | string | Provider model identifier. |
| `label` | string \| null | Display name. |
| `small_description` | string \| null | Short description. |
| `intelligence` | integer \| null | Intelligence rating, 1-5. |
| `reasoning` | integer \| null | Reasoning rating, 1-5. |
| `cost` | integer \| null | Cost-efficiency rating, 1-5 (5 = cheapest). |
| `speed` | integer \| null | Speed rating, 1-5. |
| `input_price_per_1m_tokens` | number | Listed price per 1 million input tokens, in USD. |
| `output_price_per_1m_tokens` | number | Listed price per 1 million output tokens, in USD. |
| `status` | string | `visible` (shown in model pickers), `not_visible_but_supported` (hidden from model pickers but still supported) or `not_supported`. |
| `active_in_conversations` | boolean | Available for `conversation` assistants. |
| `active_in_tickets` | boolean | Available for `support-ticket` assistants. |
| `active_in_ai_chat` | boolean | Available for `ai-chat` assistants. |
| `active_in_voice` | boolean | Available for `voice` assistants. |
| `provider_metadata` | object \| null | Provider details such as `context_length` and `architecture`. Provider pricing is removed. |
| `created_at` | string (date-time) | Read-only. Creation timestamp. |
| `updated_at` | string (date-time) | Read-only. Last update timestamp. |
| `deleted_at` | string (date-time) \| null | Read-only. Always `null` in results. |

Pick a model whose `status` is `visible` and whose `active_in_*` flag matches the assistant type.

#### Related

- [AI Assistants](#ai-assistants)
- [Create an AI assistant](#ai-assistants--create)

<a id="ai-models--list"></a>

### List AI models

Source: https://www.achieveapex.com/docs/api-reference/ai-models/list

Return the AI model catalog, with optional filters and search.

#### Endpoint

`GET /ai-models`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | `visible`, `not_visible_but_supported` or `not_supported`. |
| `provider` | string | No | `openai` or `openrouter`. |
| `active_in_conversations` | boolean | No | Models for conversation assistants. |
| `active_in_tickets` | boolean | No | Models for support-ticket assistants. |
| `active_in_ai_chat` | boolean | No | Models for AI chat assistants. |
| `active_in_voice` | boolean | No | Models for voice assistants. |
| `model_name[$ilike]` | string | No | Case-insensitive pattern, e.g. `%gpt%`. Also available on `label`. |
| `searchTerm` | string | No | Searches `model_name`, `label` and `small_description`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | integer | No | `1` ascending, `-1` descending, e.g. `$sort[label]=1`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/ai-models \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'status=visible' \
  --data-urlencode 'active_in_conversations=true' \
  --data-urlencode '$sort[label]=1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 24,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 12,
      "provider": "openrouter",
      "model_name": "openai/gpt-4.1",
      "label": "GPT-4.1",
      "small_description": "General purpose model with long context",
      "intelligence": 4,
      "reasoning": 3,
      "cost": 3,
      "speed": 4,
      "input_price_per_1m_tokens": 3.5,
      "output_price_per_1m_tokens": 14,
      "status": "visible",
      "active_in_conversations": true,
      "active_in_tickets": true,
      "active_in_ai_chat": true,
      "active_in_voice": false,
      "deleted_at": null
    }
  ]
}
```

<a id="ai-models--get"></a>

### Get an AI model

Source: https://www.achieveapex.com/docs/api-reference/ai-models/get

Retrieve one AI model by ID.

#### Endpoint

`GET /ai-models/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/ai-models/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 12,
  "provider": "openrouter",
  "model_name": "openai/gpt-4.1",
  "label": "GPT-4.1",
  "status": "visible",
  "active_in_conversations": true,
  "active_in_tickets": true,
  "active_in_ai_chat": true,
  "active_in_voice": false,
  "input_price_per_1m_tokens": 3.5,
  "output_price_per_1m_tokens": 14,
  "provider_metadata": {
    "context_length": 1047576,
    "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["text"] }
  },
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-04-02T09:00:00.000Z",
  "deleted_at": null
}
```

Returns the full [AI model object](#ai-models) (shortened above).

#### Errors

| Status | When |
|---|---|
| `404` | The model does not exist or is deleted. |

---

## API Tools

<a id="api-tools"></a>

### API Tools overview

Source: https://www.achieveapex.com/docs/api-reference/api-tools

An API tool describes an external HTTP request that AI assistants can make: the endpoint, method, headers, and the parameters the AI fills in or that are always fixed. Create a tool once, then attach it to assistants through their `api_tools` field.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/api-tools` | [List API tools](#api-tools--list) |
| `GET` | `/api-tools/:id` | [Get an API tool](#api-tools--get) |
| `POST` | `/api-tools` | [Create an API tool](#api-tools--create) |
| `PATCH` | `/api-tools/:id` | [Update an API tool](#api-tools--update) |
| `DELETE` | `/api-tools/:id` | [Delete an API tool](#api-tools--delete) |

Reads are limited to your API key's organization.

#### The API tool object

```json
{
  "id": 88,
  "organization_id": 27,
  "name": "check_order_status",
  "description": "Looks up the current status of a customer order.",
  "endpoint": "https://orders.example.com/orders/{order_id}",
  "method": "GET",
  "headers": { "Authorization": "Bearer EXTERNAL_API_TOKEN" },
  "url_parameters": [
    {
      "id": "order-id",
      "name": "order_id",
      "type": "string",
      "description": "The customer's order ID",
      "required": true,
      "value_source": "ai",
      "location": "path"
    }
  ],
  "body_parameters": [],
  "parameters_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "The customer's order ID" }
    },
    "required": ["order_id"]
  },
  "response_example": { "status": "shipped", "tracking_number": "1Z999" },
  "created_at": "2026-04-25T12:00:00.000Z",
  "updated_at": "2026-04-25T12:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. Use it as `api_tool_id` on assistants. |
| `organization_id` | integer | Required on create. Your API key's organization. |
| `name` | string | Required. Tool name shown to the AI. |
| `description` | string | What the tool does; the AI reads it to decide when to call the tool. |
| `endpoint` | string | Required. Full URL. Path placeholders such as `{order_id}`, `:order_id` or `{{order_id}}` are replaced with parameter values. |
| `method` | string | Required. `GET` or `POST`. |
| `parameters_schema` | object | Required. JSON Schema (`type: "object"`, `properties`, `required`) of the arguments the AI provides. |
| `url_parameters` | array \| null | Path and query parameters (see below). |
| `body_parameters` | array \| null | JSON body parameters for `POST` tools (see below). |
| `headers` | object \| null | Headers sent with every request, e.g. credentials for the external API. They are returned as stored, so treat responses as sensitive. |
| `response_example` | object \| null | Example response, for reference. |
| `created_at` | string (date-time) | Read-only. Creation timestamp. |
| `updated_at` | string (date-time) | Read-only. Last update timestamp. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the tool is deleted. |

##### Parameter object

Items of `url_parameters` and `body_parameters`:

| Field | Type | Description |
|---|---|---|
| `id` | string | Your own unique ID for the parameter. |
| `name` | string | Name sent to the external API (query key, path placeholder or body key). |
| `type` | string | `string`, `number`, `integer`, `boolean`, `array` or `object`. |
| `description` | string | Tells the AI what value to provide. |
| `required` | boolean | The request fails if the value is missing. |
| `value_source` | string | `ai` (default): the AI provides the value. `fixed`: `fixed_value` is always sent. |
| `fixed_value` | any | Value sent when `value_source` is `fixed`. |
| `location` | string | URL parameters only: `path` (replaces a placeholder in `endpoint`) or `query`. |

#### Attach a tool to an assistant

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistants/123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_tools": [
      { "api_tool_id": 88, "description": "Check Order Status", "when_to_use": "Use when the customer asks about an order status." }
    ]
  }'
```

The assistant's `api_tools` array replaces the previous one, so include every tool the assistant should keep.

#### Related

- [AI Assistants](#ai-assistants)
- [Update an AI assistant](#ai-assistants--update)

<a id="api-tools--list"></a>

### List API tools

Source: https://www.achieveapex.com/docs/api-reference/api-tools/list

Return the API tools of your organization.

#### Endpoint

`GET /api-tools`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Exact name match. |
| `method` | string | No | `GET` or `POST`. |
| `id[$in][]` | integer | No | Only these IDs. Repeat for each ID. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | integer | No | `1` ascending, `-1` descending, e.g. `$sort[name]=1`. |
| `$select[]` | string | No | Return only these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/api-tools \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[name]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 88,
      "organization_id": 27,
      "name": "check_order_status",
      "description": "Looks up an order by order number.",
      "endpoint": "https://orders.example.com/api/orders/{order_number}",
      "method": "GET",
      "url_parameters": [
        { "id": "order-number", "name": "order_number", "type": "string", "description": "Customer order number", "required": true, "value_source": "ai", "location": "path" }
      ],
      "body_parameters": [],
      "parameters_schema": { "type": "object", "properties": { "order_number": { "type": "string" } }, "required": ["order_number"] },
      "headers": { "X-API-Key": "YOUR_ORDER_API_KEY" },
      "response_example": { "status": "shipped" },
      "created_at": "2026-04-25T12:00:00.000Z",
      "updated_at": "2026-04-25T12:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="api-tools--get"></a>

### Get an API tool

Source: https://www.achieveapex.com/docs/api-reference/api-tools/get

Retrieve one API tool by ID.

#### Endpoint

`GET /api-tools/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/api-tools/88 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The [API tool object](#api-tools).

```json
{
  "id": 88,
  "organization_id": 27,
  "name": "check_order_status",
  "description": "Looks up an order by order number.",
  "endpoint": "https://orders.example.com/api/orders/{order_number}",
  "method": "GET",
  "url_parameters": [
    { "id": "order-number", "name": "order_number", "type": "string", "description": "Customer order number", "required": true, "value_source": "ai", "location": "path" }
  ],
  "body_parameters": [],
  "parameters_schema": { "type": "object", "properties": { "order_number": { "type": "string" } }, "required": ["order_number"] },
  "headers": { "X-API-Key": "YOUR_ORDER_API_KEY" },
  "response_example": { "status": "shipped" },
  "created_at": "2026-04-25T12:00:00.000Z",
  "updated_at": "2026-04-25T12:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404` | The tool does not exist, is deleted or belongs to another organization. |

<a id="api-tools--create"></a>

### Create an API tool

Source: https://www.achieveapex.com/docs/api-reference/api-tools/create

Create a reusable HTTP tool. Attach it to assistants afterwards through their `api_tools` field.

#### Endpoint

`POST /api-tools`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your API key's organization ID. |
| `name` | string | Yes | Tool name shown to the AI. |
| `endpoint` | string | Yes | Full URL, with path placeholders such as `{order_id}`. |
| `method` | string | Yes | `GET` or `POST`. |
| `parameters_schema` | object | Yes | JSON Schema of the arguments the AI provides. Use `{ "type": "object", "properties": {} }` when there are none. |
| `description` | string | No | What the tool does. |
| `url_parameters` | array | No | Path and query [parameters](#api-tools). |
| `body_parameters` | array | No | JSON body parameters for `POST` tools. |
| `headers` | object | No | Headers sent with every request. |
| `response_example` | object | No | Example response, for reference. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/api-tools \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "order_status_lookup",
    "description": "Looks up order status by order ID",
    "endpoint": "https://api.example.com/orders/{order_id}",
    "method": "GET",
    "headers": { "X-API-Key": "YOUR_EXTERNAL_API_KEY" },
    "url_parameters": [
      {
        "id": "order-id",
        "name": "order_id",
        "type": "string",
        "description": "The order ID provided by the customer",
        "required": true,
        "value_source": "ai",
        "location": "path"
      }
    ],
    "body_parameters": [],
    "parameters_schema": {
      "type": "object",
      "properties": { "order_id": { "type": "string", "description": "The order ID provided by the customer" } },
      "required": ["order_id"]
    },
    "response_example": { "order_id": "ORD-1001", "status": "shipped" }
  }'
```

A `POST` tool with an AI value and a fixed value:

```bash
curl -X POST https://integrations.achieveapex.com/api-tools \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "create_shipment",
    "description": "Creates a shipment in the warehouse system",
    "endpoint": "https://api.example.com/shipments",
    "method": "POST",
    "headers": { "X-API-Key": "YOUR_EXTERNAL_API_KEY" },
    "body_parameters": [
      { "id": "order-id", "name": "order_id", "type": "string", "description": "Order ID to ship", "required": true, "value_source": "ai" },
      { "id": "warehouse", "name": "warehouse_id", "type": "string", "description": "Warehouse used for shipping", "required": true, "value_source": "fixed", "fixed_value": "WH-1" }
    ],
    "parameters_schema": {
      "type": "object",
      "properties": { "order_id": { "type": "string", "description": "Order ID to ship" } },
      "required": ["order_id"]
    }
  }'
```

#### Response

The created [API tool object](#api-tools), including `id`, `created_at`, `updated_at` and `deleted_at: null`.

#### Errors

| Status | When |
|---|---|
| `400` | A required field is missing, `method` is not `GET` or `POST`, or a field has the wrong type. |
| `403` | `organization_id` is missing or is not your API key's organization. |

<a id="api-tools--update"></a>

### Update an API tool

Source: https://www.achieveapex.com/docs/api-reference/api-tools/update

Partially update an API tool. Assistants that use it pick up the change on their next call.

#### Endpoint

`PATCH /api-tools/:id`

#### Body

Any of `name`, `description`, `endpoint`, `method`, `parameters_schema`, `url_parameters`, `body_parameters`, `headers`, `response_example`. Arrays and objects replace the stored value.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/api-tools/701 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Looks up order status and tracking details by order ID",
    "headers": { "X-API-Key": "NEW_EXTERNAL_API_KEY" },
    "url_parameters": [
      { "id": "order-id", "name": "order_id", "type": "string", "description": "Order ID", "required": true, "value_source": "ai", "location": "path" },
      { "id": "include", "name": "include", "type": "string", "description": "Extra data", "required": false, "value_source": "fixed", "fixed_value": "tracking", "location": "query" }
    ]
  }'
```

#### Response

The updated [API tool object](#api-tools).

```json
{
  "id": 701,
  "organization_id": 27,
  "name": "order_status_lookup",
  "description": "Looks up order status and tracking details by order ID",
  "endpoint": "https://api.example.com/orders/{order_id}",
  "method": "GET",
  "updated_at": "2026-04-25T12:45:00.000Z"
}
```

<a id="api-tools--delete"></a>

### Delete an API tool

Source: https://www.achieveapex.com/docs/api-reference/api-tools/delete

Delete an API tool. This is a soft delete: the tool gets `deleted_at` and no longer appears in list or get.

#### Endpoint

`DELETE /api-tools/:id`

Assistants keep their `api_tools` entry for the deleted tool. Remove it from each assistant with [Update an AI assistant](#ai-assistants--update) so the association list stays clean.

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/api-tools/77 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [API tool object](#api-tools), with `deleted_at` set.

```json
{
  "id": 77,
  "organization_id": 27,
  "name": "shipment_lookup",
  "deleted_at": "2026-04-25T13:00:00.000Z"
}
```

---

## Automation executions

<a id="automations-executions"></a>

### Automation executions overview

Source: https://www.achieveapex.com/docs/api-reference/automations-executions

An automation execution is one run of an automation built in the AchieveApex app. Create one to run an automation with your own input data (for example a conversation and its contact), then read it to follow its status and result. Automations themselves are built in the app; get the `automation_id` from the automation's page.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/automations-executions` | [Run an automation](#automations-executions--create) |
| `GET` | `/automations-executions` | [List executions](#automations-executions--list) |
| `GET` | `/automations-executions/:id` | [Get an execution](#automations-executions--get) |

#### The execution object

```json
{
  "id": 90210,
  "automation_id": 1200,
  "organization_id": 456,
  "conversation_id": 5001,
  "ticket_id": null,
  "contact_id": 88001,
  "triggered_by_user_id": 12,
  "triggered_by_ai_assistant_id": null,
  "campaign_id": null,
  "series_id": null,
  "series_step_id": null,
  "series_subscription_id": null,
  "initial_payload": {
    "conversation": { "id": 5001 },
    "contact": { "id": 88001, "first_name": "Maria" },
    "messages": []
  },
  "automation_flow": { "nodes": [], "edges": [], "viewport": { "x": 0, "y": 0, "zoom": 1 } },
  "status": "completed",
  "error_message": null,
  "response_body": { "ok": true },
  "started_at": "2026-02-10T15:30:00.000Z",
  "completed_at": "2026-02-10T15:30:04.000Z",
  "created_at": "2026-02-10T15:30:00.000Z",
  "updated_at": "2026-02-10T15:30:04.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `automation_id` | integer | Automation that runs. Required on create. |
| `organization_id` | integer | Organization. Required on create. |
| `conversation_id` | integer \| null | Conversation the run is about. Logged in the conversation timeline. |
| `ticket_id` | integer \| null | [Support ticket](#support-tickets) the run is about. Logged in the ticket. |
| `contact_id` | integer \| null | Contact the run is about. |
| `triggered_by_user_id` | integer \| null | User who started the run. |
| `triggered_by_ai_assistant_id` | integer \| null | AI assistant that started the run. |
| `campaign_id` | integer \| null | Campaign that started the run. |
| `series_id` / `series_step_id` / `series_subscription_id` | integer \| null | Series (drip sequence) step that started the run. |
| `initial_payload` | object \| null | Input data available to every node of the automation. |
| `automation_flow` | object \| null | Read-only. Copy of the automation's nodes and edges at the time of the run. |
| `status` | string | Read-only. `pending`, `running`, `completed`, `failed` or `cancelled`. |
| `error_message` | string \| null | Read-only. Error when the run failed. |
| `response_body` | object \| null | Read-only. Output of the last completed node, set when the run completes. |
| `started_at` | string (date-time) \| null | Read-only. |
| `completed_at` | string (date-time) \| null | Read-only. |
| `created_at` | string (date-time) | Read-only. |
| `updated_at` | string (date-time) | Read-only. |
| `deleted_at` | string (date-time) \| null | Read-only. |

<a id="automations-executions--list"></a>

### List executions

Source: https://www.achieveapex.com/docs/api-reference/automations-executions/list

List automation runs of your organization, for example the runs of one automation or the failed runs of the last day.

#### Endpoint

`GET /automations-executions`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization. Results are always limited to your API key's organization. |
| `automation_id` | integer | No | Runs of one automation. |
| `status` | string | No | `pending`, `running`, `completed`, `failed` or `cancelled`. |
| `conversation_id` / `ticket_id` / `contact_id` | integer | No | Runs about one conversation, ticket or contact. |
| `filterBySeriesId` | integer | No | Runs started by one series. |
| `created_at[$gte]` | string (date-time) | No | Date range (also `$lte`). |
| `searchTerm` | string | No | Text search inside `initial_payload`. |
| `fastJoinForAutomationExecutions` | string | No | `true` adds `automation` (`id`, `name`), `conversation` (`id`, `contact_id`, `channel`), `triggered_by_user`, `triggered_by_ai_assistant` and `series` to each item. |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[created_at]` | `1` \| `-1` | No | Sort order. |
| `$select[]` | string | No | Leave out the large `automation_flow` and `initial_payload` by selecting only the fields you need. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/automations-executions \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'automation_id=1200' \
  --data-urlencode 'status=failed' \
  --data-urlencode 'fastJoinForAutomationExecutions=true' \
  --data-urlencode '$sort[created_at]=-1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 90211,
      "automation_id": 1200,
      "organization_id": 456,
      "conversation_id": 5001,
      "status": "failed",
      "error_message": "Request failed with status code 500",
      "started_at": "2026-02-10T16:00:00.000Z",
      "completed_at": "2026-02-10T16:00:02.000Z",
      "created_at": "2026-02-10T16:00:00.000Z",
      "automation": { "id": 1200, "name": "Send order to ERP" },
      "conversation": { "id": 5001, "contact_id": 88001, "channel": "whatsapp" }
    }
  ]
}
```

See [The execution object](#automations-executions).

<a id="automations-executions--get"></a>

### Get an execution

Source: https://www.achieveapex.com/docs/api-reference/automations-executions/get

Retrieve one automation run by ID. Poll it after [running an automation](#automations-executions--create) in the background until `status` is `completed` or `failed`.

#### Endpoint

`GET /automations-executions/:id`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `fastJoinForAutomationExecutions` | string | No | `true` adds `automation`, `conversation`, `triggered_by_user`, `triggered_by_ai_assistant` and `series`. |

#### Request

```bash
curl https://integrations.achieveapex.com/automations-executions/90210 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 90210,
  "automation_id": 1200,
  "organization_id": 456,
  "conversation_id": 5001,
  "contact_id": 88001,
  "status": "completed",
  "error_message": null,
  "response_body": { "ok": true },
  "started_at": "2026-02-10T15:30:00.000Z",
  "completed_at": "2026-02-10T15:30:04.000Z",
  "created_at": "2026-02-10T15:30:00.000Z",
  "updated_at": "2026-02-10T15:30:04.000Z"
}
```

The response is the full [execution object](#automations-executions) (shortened here).

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The ID does not exist or belongs to an organization your API key cannot access. |

<a id="automations-executions--create"></a>

### Run an automation

Source: https://www.achieveapex.com/docs/api-reference/automations-executions/create

Start a run of an automation with your own input data. By default the request returns immediately with `status: pending` and the automation runs in the background; add `?sync=true` to wait until it finishes.

#### Endpoint

`POST /automations-executions`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `sync` | string | No | `true` waits for the run to finish and returns it with its final `status` and `response_body`. |

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `automation_id` | integer | Yes | Automation to run. |
| `organization_id` | integer | Yes | Your organization ID. |
| `initial_payload` | object | No | Input data for the automation's nodes. |
| `conversation_id` | integer | No | Conversation the run is about. The start and end of the run are logged in the conversation. |
| `ticket_id` | integer | No | Support ticket the run is about. The run is logged in the ticket. |
| `contact_id` | integer | No | Contact the run is about. |
| `triggered_by_user_id` | integer | No | User to record as the one who started the run. |

Unknown fields are rejected with `400 Bad Request`.

#### Request

Run an automation on a conversation, giving it the conversation, the contact and recent messages (the same payload the app's "Run automation" action builds):

```bash
curl -X POST https://integrations.achieveapex.com/automations-executions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "automation_id": 1200,
    "organization_id": 456,
    "conversation_id": 5001,
    "contact_id": 88001,
    "initial_payload": {
      "conversation": { "id": 5001, "channel": "whatsapp" },
      "contact": { "id": 88001, "first_name": "Maria" },
      "messages": [
        { "message_type": "text", "message_text": "Hello! Is my order ready?", "destination": "incoming" }
      ]
    }
  }'
```

Wait for the result:

```bash
curl -X POST "https://integrations.achieveapex.com/automations-executions?sync=true" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "automation_id": 1200, "organization_id": 456, "initial_payload": { "email": "maria@example.com" } }'
```

#### Response

The [execution](#automations-executions):

```json
{
  "id": 90210,
  "automation_id": 1200,
  "organization_id": 456,
  "conversation_id": 5001,
  "contact_id": 88001,
  "initial_payload": { "conversation": { "id": 5001, "channel": "whatsapp" }, "contact": { "id": 88001, "first_name": "Maria" }, "messages": [] },
  "status": "pending",
  "error_message": null,
  "response_body": null,
  "started_at": null,
  "completed_at": null,
  "created_at": "2026-02-10T15:30:00.000Z"
}
```

With `sync=true`, `status` is `completed` or `failed` and `response_body` holds the output of the last node. Poll [Get an execution](#automations-executions--get) to follow a background run.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | A required field is missing, an unknown field was sent, or the organization reached its plan's automation run limit. |
| `500` | The automation does not exist. |

---

## Campaign Segments

<a id="campaign-segments"></a>

### Campaign Segments overview

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments

A campaign segment is a saved audience: the contacts that match a set of rules, for one sending channel. Campaigns and automations send to segments. A segment is built either with the visual builder (`builder_type: "manual"`, rules in `query`) or with AI (`builder_type: "ai"`, a SQL selector in `ai_sql_query`).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/campaign-segments` | [List segments](#campaign-segments--list) |
| `GET` | `/campaign-segments/:id` | [Get a segment](#campaign-segments--get) |
| `PATCH` | `/campaign-segments/:id` | [Update a segment](#campaign-segments--update) |
| `DELETE` | `/campaign-segments/:id` | [Delete a segment](#campaign-segments--delete) |
| `POST` | `/contacts-segments-schema-builder` | [Get the fields you can filter on](#campaign-segments--schema-builder) |
| `POST` | `/contacts-segments-run-query` | [Preview the contacts of a segment](#campaign-segments--run-query) |

Reads are limited to your API key's organization. Creating and splitting segments is currently only available in the AchieveApex app.

#### The segment object

```json
{
  "id": 501,
  "organization_id": 456,
  "created_by_user_id": 789,
  "name": "VIP customers",
  "channel": "whatsapp",
  "builder_type": "manual",
  "query": {
    "operator": "and",
    "conditions": [
      { "entity": "contacts", "field": "tags", "operator": "equals", "value": "vip" },
      { "entity": "contacts", "field": "email", "operator": "is_not_empty" }
    ]
  },
  "ai_sql_query": null,
  "ai_explanation": null,
  "ai_prompt": null,
  "total_persons": "1200",
  "created_at": "2026-02-01T10:00:00.000Z",
  "updated_at": "2026-02-05T14:30:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Read-only. Organization that owns the segment. |
| `created_by_user_id` | integer | Read-only. User who created the segment. |
| `name` | string | Segment name. |
| `channel` | string | `whatsapp`, `instagram`, `messenger`, `email`, `automation`, `sms` or `ai_calling`. Only contacts reachable on this channel are included. |
| `builder_type` | string | `manual` (rules in `query`) or `ai` (selector in `ai_sql_query`). |
| `query` | object \| null | Manual rules (see below). |
| `ai_sql_query` | string \| null | AI segments: a read-only `SELECT` that returns a `contact_id` column, up to 20000 characters. It is validated and test-run, scoped to your organization, before it is saved; only allowed tables can be used. |
| `ai_explanation` | string \| null | AI segments: plain-language explanation of the selector, up to 5000 characters. |
| `ai_prompt` | string \| null | AI segments: the request the selector was generated from, up to 5000 characters. |
| `total_persons` | string \| integer | Read-only. Number of contacts that currently match, computed on list and get. |
| `created_at` | string (date-time) | Read-only. Creation timestamp. |
| `updated_at` | string (date-time) | Read-only. Last update timestamp. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the segment is deleted. |

##### The `query` object

```json
{
  "operator": "and",
  "conditions": [
    { "entity": "contacts", "field": "first_name", "operator": "contains", "value": "ana" },
    {
      "type": "group",
      "operator": "or",
      "conditions": [
        { "entity": "deals", "field": "tags", "operator": "equals", "value": "won-2025" },
        { "isCustomField": true, "customFieldId": 31, "operator": "greater", "value": 100 }
      ]
    },
    { "entity": "contacts", "field": "id", "operator": "between", "value": { "start": 1000, "end": 5000 } }
  ],
  "destination_countries": ["US", "CO"]
}
```

| Key | Description |
|---|---|
| `operator` | `and` or `or`, combines `conditions`. |
| `conditions[]` | A condition, or a nested group `{ "type": "group", "operator", "conditions" }`. |
| `conditions[].entity` | `contacts` (default), `deals`, `companies` or `conversation_events`. |
| `conditions[].field` | Field name from the [schema builder](#campaign-segments--schema-builder). `tags` matches a tag name (`equals` / `not_equals`). `phone_country` takes ISO country codes (`in`, `not_in`, `equals`, `not_equals`). |
| `conditions[].isCustomField` / `customFieldId` | Filter on a custom field by its ID. |
| `conditions[].operator` | `equals`, `not_equals`, `contains`, `not_contains`, `greater`, `less`, `between`, `not_between`, `is_empty`, `is_not_empty`. |
| `conditions[].value` | The value to compare. `between` takes `{ "start", "end" }`; `is_empty` / `is_not_empty` take none. |
| `destination_countries` | SMS and AI calling only: limit to these phone countries (within your organization's allowed destinations). |

#### Related

- [Contacts](#contacts)

<a id="campaign-segments--list"></a>

### List segments

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/list

Return the segments of your organization, each with its current `total_persons` count.

#### Endpoint

`GET /campaign-segments`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `channel` | string | No | `whatsapp`, `instagram`, `messenger`, `email`, `automation`, `sms` or `ai_calling`. |
| `builder_type` | string | No | `manual` or `ai`. |
| `searchTerm` | string | No | Case-insensitive search on `name`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | integer | No | `1` ascending, `-1` descending. With `searchTerm` only `name`, `channel`, `created_at`, `updated_at` and `id` can be sorted. |
| `$select[]` | string | No | Return only these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/campaign-segments \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'channel=whatsapp' \
  --data-urlencode '$sort[created_at]=-1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 12,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 501,
      "organization_id": 456,
      "created_by_user_id": 789,
      "name": "VIP customers",
      "channel": "whatsapp",
      "builder_type": "manual",
      "query": { "operator": "and", "conditions": [ { "entity": "contacts", "field": "tags", "operator": "equals", "value": "vip" } ] },
      "ai_sql_query": null,
      "ai_explanation": null,
      "ai_prompt": null,
      "total_persons": "1200",
      "created_at": "2026-02-01T10:00:00.000Z",
      "updated_at": "2026-02-05T14:30:00.000Z",
      "deleted_at": null
    }
  ]
}
```

Counting contacts runs the segment rules, so large pages of segments are slower than other lists.

<a id="campaign-segments--get"></a>

### Get a segment

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/get

Retrieve one segment with its current `total_persons` count.

#### Endpoint

`GET /campaign-segments/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/campaign-segments/501 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 501,
  "organization_id": 456,
  "created_by_user_id": 789,
  "name": "VIP customers",
  "channel": "whatsapp",
  "builder_type": "manual",
  "query": { "operator": "and", "conditions": [ { "entity": "contacts", "field": "tags", "operator": "equals", "value": "vip" } ] },
  "ai_sql_query": null,
  "ai_explanation": null,
  "ai_prompt": null,
  "total_persons": "1200",
  "created_at": "2026-02-01T10:00:00.000Z",
  "updated_at": "2026-02-05T14:30:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404` | The segment does not exist, is deleted or belongs to another organization. |

<a id="campaign-segments--update"></a>

### Update a segment

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/update

Partially update a segment: rename it, change its channel or replace its rules.

#### Endpoint

`PATCH /campaign-segments/:id`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Segment name. |
| `channel` | string | No | `whatsapp`, `instagram`, `messenger`, `email`, `automation`, `sms` or `ai_calling`. |
| `builder_type` | string | No | `manual` or `ai`. |
| `query` | object \| null | Manual rules. Replaces the stored rules; see [the query object](#campaign-segments). |
| `ai_sql_query` | string \| null | AI selector. Validated and test-run before saving; an empty string clears it. |
| `ai_explanation` | string \| null | Explanation of the AI selector. |
| `ai_prompt` | string \| null | Request the AI selector was generated from. |

#### Request

Replace the rules:

```bash
curl -X PATCH https://integrations.achieveapex.com/campaign-segments/501 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "operator": "and",
      "conditions": [
        { "entity": "contacts", "field": "tags", "operator": "equals", "value": "vip" },
        { "entity": "contacts", "field": "email", "operator": "is_not_empty" }
      ]
    }
  }'
```

Rename:

```bash
curl -X PATCH https://integrations.achieveapex.com/campaign-segments/501 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP customers (Q1)" }'
```

#### Response

The updated [segment object](#campaign-segments) (without `total_persons`).

`query` rules are not validated on save: an invalid field or operator is stored as is (its `total_persons` then reads 0). Check the result with [Preview the contacts of a segment](#campaign-segments--run-query).

#### Errors

| Status | When |
|---|---|
| `400` | Invalid `channel` or `builder_type`, or an `ai_sql_query` that is not a valid read-only selector or fails when run. |
| `404` | The segment does not exist, is deleted or belongs to another organization. |

<a id="campaign-segments--delete"></a>

### Delete a segment

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/delete

Delete a segment. This is a soft delete: the segment gets `deleted_at` and no longer appears in list or get.

#### Endpoint

`DELETE /campaign-segments/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/campaign-segments/501 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [segment object](#campaign-segments), with `deleted_at` set.

```json
{
  "id": 501,
  "organization_id": 456,
  "name": "VIP customers",
  "channel": "whatsapp",
  "deleted_at": "2026-02-10T09:00:00.000Z"
}
```

<a id="campaign-segments--export-contacts"></a>

### Export campaign segment contacts

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/export-contacts

Start an **Excel export** of all contacts matching a segment. The segment preview **Export** button uses the generic `export-data` service.

#### Endpoint

`POST /export-data`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/export-data \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "campaign-segment-contacts",
    "organization_id": 456,
    "campaign_segment_id": 501
  }'
```

#### Response

```json
{
  "success": true,
  "fileUrl": "https://...",
  "exported": 1200,
  "segment_name": "VIP customers"
}
```

The UI opens `fileUrl` in a new tab when `success` is true.

#### Notes

- Export may be **asynchronous** on large segments; behavior depends on your backend.
- Segment `query` must be non-empty for the preview export path in the app (the UI blocks empty queries).

<a id="campaign-segments--schema-builder"></a>

### Get segment fields

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/schema-builder

Return every field you can filter on in a segment `query`, grouped by entity, with its type, label and allowed operators. Includes your organization's custom fields, tags, team members and conversation events. Nothing is saved.

#### Endpoint

`POST /contacts-segments-schema-builder`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your API key's organization ID. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/contacts-segments-schema-builder \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "organization_id": 456 }'
```

#### Response

```json
{
  "contacts": {
    "label": "Contact Properties",
    "fields": {
      "id": { "type": "number", "label": "Contact ID", "operators": ["equals", "not_equals", "greater", "less", "between", "not_between"] },
      "first_name": { "type": "string", "label": "Contact First Name", "operators": ["equals", "contains", "not_contains", "not_equals", "is_empty", "is_not_empty"] },
      "membership_level": {
        "type": "select",
        "label": "Membership level",
        "operators": ["equals", "contains", "not_contains"],
        "options": ["gold", "silver"],
        "isCustomField": true,
        "customFieldId": 31
      }
    }
  },
  "companies": { "label": "Company Properties", "fields": {} },
  "deals": { "label": "Deal Properties", "fields": {} },
  "tickets": { "label": "Ticket Properties", "fields": {} },
  "conversations": { "label": "Conversation Properties", "fields": {} },
  "conversation_events": { "label": "Conversation Events", "fields": {} }
}
```

Use the group key as a condition's `entity` and the field key as its `field`. For custom fields (`isCustomField: true`) send `isCustomField` and `customFieldId` instead of `field`. Some fields include `options` (tags, users, select values).

#### Errors

| Status | When |
|---|---|
| `403` | `organization_id` is not your API key's organization. |
| `500` | `organization_id` is missing or the organization does not exist. |

<a id="campaign-segments--run-query"></a>

### Preview the contacts of a segment

Source: https://www.achieveapex.com/docs/api-reference/campaign-segments/run-query

Return a page of the contacts that currently match a saved segment. Nothing is saved or sent.

#### Endpoint

`POST /contacts-segments-run-query`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `campaign_segment_id` | integer | Yes | Segment to run. |
| `organization_id` | integer | Yes | Your API key's organization ID (the segment must belong to it). |
| `$limit` | integer | No | Page size. Default 10, max 100. |
| `$skip` | integer | No | Number of contacts to skip. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/contacts-segments-run-query \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_segment_id": 501,
    "organization_id": 456,
    "$skip": 0,
    "$limit": 50
  }'
```

#### Response

```json
{
  "total": 1200,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "conversation_id": 99120,
      "contact_id": 88001,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "5551234567",
      "phone_country_code": "+1",
      "channel_whatsapp_wa_id": "15551234567",
      "channel_whatsapp_wa_user_id": null,
      "channel_whatsapp_username": null
    }
  ]
}
```

Each row is one contact. `conversation_id` is the contact's conversation on the segment channel (or `null`). The `channel_whatsapp_*` columns are only present for `whatsapp` segments. A segment without rules returns `total: 0`.

#### Errors

| Status | When |
|---|---|
| `400` | `campaign_segment_id` is missing, or an AI segment's selector fails. |
| `403` | The segment does not belong to `organization_id`, or `organization_id` is not your API key's organization. |
| `404` | The segment does not exist or is deleted. |

---

## Companies

<a id="companies"></a>

### Companies overview

Source: https://www.achieveapex.com/docs/api-reference/companies

A company is an account or business your contacts and deals belong to. Use this resource to keep company records in sync, link contacts and deals to them, and store custom fields and tags.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/companies` | [List companies](#companies--list) |
| `GET` | `/companies/:id` | [Get a company](#companies--get) |
| `POST` | `/companies` | [Create a company](#companies--create) |
| `PATCH` | `/companies/:id` | [Update a company](#companies--update) |
| `DELETE` | `/companies/:id` | [Delete a company](#companies--delete) |
| `POST` | `/companies` + `X-Service-Method: search` | [Search companies](#companies--search) |

Reads are limited to your API key's organization. Pass `organization_id` as a filter to work with one organization.

#### The company object

```json
{
  "id": 101,
  "name": "Acme Corporation",
  "organization_id": 456,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "custom_fields_by_key": {
    "annual_revenue": 25000000
  },
  "custom_fields_by_name": {
    "Annual revenue": 25000000
  },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 31,
      "custom_field_key": "annual_revenue",
      "custom_field_name": "Annual revenue",
      "custom_field_value": 25000000
    }
  ],
  "tags": [
    { "id": 9, "name": "Enterprise", "color": "#2563EB" }
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Company name. Required on create. |
| `organization_id` | integer | Organization that owns the company. Required on create. |
| `created_by_user_id` | integer \| null | Read-only. User who created the company (the API key's user). |
| `owned_by_user_id` | integer \| null | User who owns the company. Defaults to the API key's user. |
| `custom_fields_by_key` | object | Custom field values keyed by the field `key` (see [Custom fields](#custom-fields), `entity_type=company`). This is the field you write. |
| `custom_fields_by_name` | object | Read-only. Same values keyed by the field name. |
| `custom_fields_meta_data` | array | Read-only. One entry per value: `custom_field_id`, `custom_field_key`, `custom_field_name`, `custom_field_value`. |
| `tags` | array | Tags as `{ id, name, color }` objects. Default `[]`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the company is deleted. |

#### Related

- [Contacts](#contacts)
- [Deals](#deals)
- [Custom fields](#custom-fields)
- [Errors](#companies--errors)

<a id="companies--list"></a>

### List companies

Source: https://www.achieveapex.com/docs/api-reference/companies/list

Returns a paginated list of companies, with optional filters and a name search.

#### Endpoint

`GET /companies`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only companies of this organization. |
| any company field | mixed | No | Filter with Feathers syntax, e.g. `owned_by_user_id=789`, `created_at[$gte]=2026-01-01`. |
| `searchTerm` | string | No | Case-insensitive match on `name`. |
| `view_id` | integer | No | Apply the filters of a saved companies view. |
| `fastJoinForCompanyList` | string | No | Set to `true` to embed `organization`, `creator` and `owner` objects. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. With `searchTerm` the default is `created_at` descending. |
| `$select[]` | string | No | Only return these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/companies \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'searchTerm=acme' \
  --data-urlencode 'fastJoinForCompanyList=true' \
  --data-urlencode '$limit=25'
```

#### Response

```json
{
  "total": 1,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 101,
      "name": "Acme Corporation",
      "organization_id": 456,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "tags": [],
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "deleted_at": null,
      "organization": { "id": 456, "name": "My Business" },
      "creator": { "id": 789, "first_name": "Ana", "last_name": "Lopez", "email": "ana@example.com" },
      "owner": { "id": 789, "first_name": "Ana", "last_name": "Lopez", "email": "ana@example.com" }
    }
  ]
}
```

Each item is a full [company object](#companies); it is shortened here.

<a id="companies--get"></a>

### Get a company

Source: https://www.achieveapex.com/docs/api-reference/companies/get

Returns one company by ID.

#### Endpoint

`GET /companies/:id`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `fastJoinForCompanyList` | string | No | Set to `true` to embed `organization`, `creator` and `owner` objects. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/companies/101 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [company object](#companies).

```json
{
  "id": 101,
  "name": "Acme Corporation",
  "organization_id": 456,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "custom_fields_by_key": { "annual_revenue": 25000000 },
  "custom_fields_by_name": { "Annual revenue": 25000000 },
  "tags": [],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

<a id="companies--create"></a>

### Create a company

Source: https://www.achieveapex.com/docs/api-reference/companies/create

Creates a company.

#### Endpoint

`POST /companies`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the company in. |
| `name` | string | Yes | Company name. |
| `owned_by_user_id` | integer | No | Owner. Defaults to the API key's user. |
| `custom_fields_by_key` | object | No | Custom field values keyed by field `key`. Values are validated against the field type; unknown keys are rejected. |
| `tags` | array | No | Tags as `{ id, name, color }` objects. |

Fields not in the [company object](#companies) are rejected. `created_by_user_id` is always set to the API key's user.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/companies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Globex",
    "custom_fields_by_key": { "annual_revenue": 1200000 }
  }'
```

#### Response

```json
{
  "id": 102,
  "name": "Globex",
  "organization_id": 456,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "custom_fields_by_key": { "annual_revenue": 1200000 },
  "custom_fields_by_name": { "Annual revenue": 1200000 },
  "tags": [],
  "created_at": "2026-01-02T00:00:00.000Z",
  "updated_at": "2026-01-02T00:00:00.000Z",
  "deleted_at": null
}
```

<a id="companies--update"></a>

### Update a company

Source: https://www.achieveapex.com/docs/api-reference/companies/update

Partially updates a company. Only the fields you send change.

#### Endpoint

`PATCH /companies/:id`

#### Body

Any writable field of the [company object](#companies). `custom_fields_by_key` is merged with the existing values; send a key with `null` to clear it.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/companies/101 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp.",
    "owned_by_user_id": 790
  }'
```

#### Response

Returns the updated [company object](#companies).

```json
{
  "id": 101,
  "name": "Acme Corp.",
  "organization_id": 456,
  "created_by_user_id": 789,
  "owned_by_user_id": 790,
  "tags": [],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-03T00:00:00.000Z",
  "deleted_at": null
}
```

<a id="companies--delete"></a>

### Delete a company

Source: https://www.achieveapex.com/docs/api-reference/companies/delete

Deletes a company. This is a soft delete: the company gets a `deleted_at` timestamp and no longer appears in list, get or search. Contacts, deals, activities and notes that pointed to it get `company_id = null`.

#### Endpoint

`DELETE /companies/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/companies/101 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [company object](#companies) with `deleted_at` set.

```json
{
  "id": 101,
  "name": "Acme Corporation",
  "organization_id": 456,
  "updated_at": "2026-01-04T00:00:00.000Z",
  "deleted_at": "2026-01-04T00:00:00.000Z"
}
```

<a id="companies--errors"></a>

### Companies errors

Source: https://www.achieveapex.com/docs/api-reference/companies/errors

Errors use the standard Feathers error format.

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query: missing `name`, unknown field, invalid custom field key or value. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, or the record belongs to an organization the key cannot access. |
| `404 Not Found` | The company does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error. |

<a id="companies--search"></a>

### Search companies

Source: https://www.achieveapex.com/docs/api-reference/companies/search

Searches companies of one organization by name (case-insensitive, partial match), sorted by name.

#### Endpoint

`POST /companies` with header `X-Service-Method: search`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to search in. |
| `searchTerm` | string | Yes | Text to find in the company name. Fewer than 2 characters returns an empty page. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/companies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Service-Method: search" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "searchTerm": "acme",
    "$limit": 10
  }'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 101,
      "name": "Acme Corporation",
      "organization_id": 456,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "deleted_at": null
    }
  ]
}
```

Each item is a full [company object](#companies); it is shortened here.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `organization_id` is missing or not a positive integer. |
| `403 Forbidden` | Your key cannot access `organization_id`. |

---

## Contacts

<a id="contacts"></a>

### Contacts overview

Source: https://www.achieveapex.com/docs/api-reference/contacts

A contact is a person your organization talks to: a lead, a customer or someone who wrote to one of your channels (WhatsApp, Instagram, Messenger, SMS, webchat). Use this resource to sync people from another system, look them up by phone or email, and keep their custom fields, tags and Do Not Disturb flags up to date.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/contacts` | [List contacts](#contacts--list) |
| `GET` | `/contacts/:id` | [Get a contact](#contacts--get) |
| `POST` | `/contacts` | [Create a contact](#contacts--create) |
| `PATCH` | `/contacts/:id` | [Update a contact](#contacts--update) |
| `DELETE` | `/contacts/:id` | [Delete a contact](#contacts--delete) |
| `POST` | `/contacts` + `X-Service-Method: search` | [Search contacts](#contacts--search) |

Reads are limited to your API key's organization. Pass `organization_id` as a filter to work with one organization.

#### The contact object

```json
{
  "id": 123,
  "organization_id": 456,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "avatar_url": null,
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "phone": "2025550143",
  "company_id": 101,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "system_type": "contact",
  "channel_whatsapp_wa_id": "12025550143",
  "channel_whatsapp_wa_user_id": null,
  "channel_whatsapp_username": null,
  "channel_instagram_user_id": null,
  "meta_psid": null,
  "meta_facebook_user_id": null,
  "whatsapp_blacklist": false,
  "whatsapp_blacklist_reason": null,
  "sms_blacklist": false,
  "sms_blacklist_reason": null,
  "sms_opt_in_at": null,
  "sms_opt_in_source": null,
  "voice_blacklist": false,
  "voice_blacklist_reason": null,
  "instagram_blacklist": false,
  "instagram_blacklist_reason": null,
  "messenger_blacklist": false,
  "messenger_blacklist_reason": null,
  "dnd_updated_at": null,
  "dnd_source": null,
  "custom_fields_by_key": {
    "industry": "Technology"
  },
  "custom_fields_by_name": {
    "Industry": "Technology"
  },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 12,
      "custom_field_key": "industry",
      "custom_field_name": "Industry",
      "custom_field_value": "Technology"
    }
  ],
  "tags": [
    { "id": 7, "name": "VIP", "color": "#F59E0B" }
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the contact. Required on create. |
| `first_name` | string \| null | First name. |
| `last_name` | string \| null | Last name. |
| `email` | string \| null | Email address (must be a valid email). |
| `avatar_url` | string \| null | Profile picture URL or storage key. |
| `phone_country_code` | string \| null | Dialing code with `+`, e.g. `+1`. Filled automatically when `phone` is sent in international format. |
| `phone_country_iso` | string \| null | ISO 3166 country code of the phone, e.g. `US`. Filled automatically when it can be detected. |
| `phone` | string \| null | National phone number. An international number such as `+12025550143` is split into `phone_country_code`, `phone_country_iso` and `phone`. |
| `company_id` | integer \| null | [Company](#companies) the contact belongs to. |
| `created_by_user_id` | integer \| null | Read-only. User who created the contact (the API key's user). |
| `owned_by_user_id` | integer \| null | User who owns the contact. Defaults to the API key's user; must be a member of the organization. |
| `system_type` | string | Classification of the record: `lead`, `contact` or `conversation`. |
| `channel_whatsapp_wa_id` | string \| null | WhatsApp ID (phone number in international format, digits only). |
| `channel_whatsapp_wa_user_id` | string \| null | WhatsApp Business-Scoped User ID, used when WhatsApp hides the phone number. |
| `channel_whatsapp_username` | string \| null | WhatsApp username, when WhatsApp provides one. |
| `channel_instagram_user_id` | string \| null | Instagram-scoped user ID of the contact. |
| `meta_psid` | string \| null | Facebook Messenger page-scoped ID of the contact. |
| `meta_facebook_user_id` | string \| null | Facebook user ID of the contact. |
| `whatsapp_blacklist` | boolean | Do Not Disturb on WhatsApp: blocks every outbound WhatsApp message. Default `false`. |
| `whatsapp_blacklist_reason` | string \| null | Why WhatsApp DND was turned on. |
| `sms_blacklist` | boolean | Do Not Disturb on SMS. Default `false`. |
| `sms_blacklist_reason` | string \| null | Why SMS DND was turned on. |
| `sms_opt_in_at` | string (date-time) \| null | When the contact opted in to SMS. |
| `sms_opt_in_source` | string \| null | Where the SMS opt-in came from. |
| `voice_blacklist` | boolean | Do Not Disturb on voice calls. Default `false`. |
| `voice_blacklist_reason` | string \| null | Why voice DND was turned on. |
| `instagram_blacklist` | boolean | Do Not Disturb on Instagram. Default `false`. |
| `instagram_blacklist_reason` | string \| null | Why Instagram DND was turned on. |
| `messenger_blacklist` | boolean | Do Not Disturb on Facebook Messenger. Default `false`. |
| `messenger_blacklist_reason` | string \| null | Why Messenger DND was turned on. |
| `dnd_updated_at` | string (date-time) \| null | Last time any DND flag changed. Set automatically when a patch changes a `*_blacklist` field. |
| `dnd_source` | string \| null | Origin of the last DND change: `manual`, `ai_assistant`, `automation`, `keyword`, `bulk` or `system`. Defaults to `manual` for API changes. |
| `custom_fields_by_key` | object | Custom field values keyed by the field `key` (see [Custom fields](#custom-fields), `entity_type=contact`). This is the field you write. |
| `custom_fields_by_name` | object | Read-only. Same values keyed by the field name. Rebuilt from `custom_fields_by_key`. |
| `custom_fields_meta_data` | array | Read-only. One entry per value: `custom_field_id`, `custom_field_key`, `custom_field_name`, `custom_field_value`. |
| `tags` | array | Tags as `{ id, name, color }` objects. Default `[]`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the contact is deleted. |

#### Related

- [Companies](#companies)
- [Deals](#deals)
- [Custom fields](#custom-fields)
- [Campaign segments](#campaign-segments)
- [Export data](#export-data)
- [Errors](#contacts--errors)

<a id="contacts--list"></a>

### List contacts

Source: https://www.achieveapex.com/docs/api-reference/contacts/list

Returns a paginated list of contacts, with optional filters, sorting and a free-text search.

#### Endpoint

`GET /contacts`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only contacts of this organization. Required when you use `searchTerm`. |
| any contact field | mixed | No | Filter with Feathers syntax, e.g. `email=jane@example.com`, `system_type=lead`, `owned_by_user_id[$in][]=789`, `created_at[$gte]=2026-01-01`. |
| `tag_ids[]` | integer[] | No | Only contacts that have at least one of these tag IDs. |
| `searchTerm` | string | No | Free-text search (at least 3 characters). Requires `organization_id` and `searchIn`. |
| `searchIn` | string | With `searchTerm` | Where to search: `all`, `name`, `phone`, `email` or `custom_field`. |
| `custom_field_name` | string | With `searchIn=custom_field` | Name of the custom field to search in. |
| `view_id` | integer | No | Apply the filters of a saved contacts view. |
| `fastJoinForContactList` | string | No | Set to `true` to embed `company` and `owner` objects in each contact. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort ascending or descending, e.g. `$sort[created_at]=-1`. |
| `$select[]` | string | No | Only return these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'system_type=lead' \
  --data-urlencode 'fastJoinForContactList=true' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$sort[created_at]=-1'
```

Search by phone:

```bash
curl -G https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'searchTerm=2025550143' \
  --data-urlencode 'searchIn=phone'
```

#### Response

```json
{
  "total": 1,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "organization_id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_country_code": "+1",
      "phone_country_iso": "US",
      "phone": "2025550143",
      "company_id": 101,
      "owned_by_user_id": 789,
      "system_type": "lead",
      "tags": [],
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "deleted_at": null,
      "company": {
        "id": 101,
        "name": "Acme Corporation",
        "organization_id": 456,
        "created_by_user_id": 789,
        "owned_by_user_id": 789
      },
      "owner": {
        "id": 789,
        "first_name": "Ana",
        "last_name": "Lopez",
        "email": "ana@example.com",
        "phone_country_code": "+1",
        "phone": "2025550100",
        "role": "user"
      }
    }
  ]
}
```

Each item is a full [contact object](#contacts); it is shortened here.

#### Notes

- With `searchTerm`, results are sorted by `first_name` unless you pass `$sort` on `first_name`, `last_name`, `email`, `created_at` or `updated_at`. Terms shorter than 3 characters (or a lone `+` or digit) return an empty page.
- `searchIn=all` also matches custom field values when the term has 4 or more characters.

<a id="contacts--get"></a>

### Get a contact

Source: https://www.achieveapex.com/docs/api-reference/contacts/get

Returns one contact by ID.

#### Endpoint

`GET /contacts/:id`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `fastJoinForContactList` | string | No | Set to `true` to embed `company` and `owner` objects. |
| `$select[]` | string | No | Only return these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/contacts/123 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [contact object](#contacts).

```json
{
  "id": 123,
  "organization_id": 456,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "phone": "2025550143",
  "company_id": 101,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "system_type": "contact",
  "custom_fields_by_key": { "industry": "Technology" },
  "custom_fields_by_name": { "Industry": "Technology" },
  "tags": [],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No contact with this ID, it was deleted, or it belongs to an organization your key cannot access. |

<a id="contacts--create"></a>

### Create a contact

Source: https://www.achieveapex.com/docs/api-reference/contacts/create

Creates a contact. If a contact with the same email, the same phone (with the same country code) or the same WhatsApp user ID already exists in the organization, that contact is updated with the data you send and returned instead of creating a duplicate.

#### Endpoint

`POST /contacts`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the contact in. |
| `first_name` | string | No | First name. |
| `last_name` | string | No | Last name. |
| `email` | string | No | Email address. |
| `phone` | string | No | Phone. Send it in international format (`+12025550143`) or as a national number together with `phone_country_code`. |
| `phone_country_code` | string | No | Dialing code, e.g. `+1`. A missing `+` is added. |
| `phone_country_iso` | string | No | ISO country code, e.g. `US`. |
| `company_id` | integer | No | Company the contact belongs to. |
| `owned_by_user_id` | integer | No | Owner. Must be a member of the organization. Defaults to the API key's user. |
| `system_type` | string | No | `lead`, `contact` or `conversation`. |
| `custom_fields_by_key` | object | No | Custom field values keyed by field `key`. Values are validated against the field type; unknown keys are rejected. |
| `tags` | array | No | Tags as `{ id, name, color }` objects. |
| `avatar_url` | string | No | Profile picture URL. |
| `channel_whatsapp_wa_id` | string | No | WhatsApp ID (international number, digits only). |

Any other writable field from the [contact object](#contacts) is accepted. `created_by_user_id` is always set to the API key's user.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+12025550199",
    "company_id": 101,
    "custom_fields_by_key": { "industry": "Retail" }
  }'
```

#### Response

```json
{
  "id": 124,
  "organization_id": 456,
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone_country_code": "+1",
  "phone_country_iso": "US",
  "phone": "2025550199",
  "company_id": 101,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "system_type": "contact",
  "custom_fields_by_key": { "industry": "Retail" },
  "custom_fields_by_name": { "Industry": "Retail" },
  "tags": [],
  "created_at": "2026-01-02T00:00:00.000Z",
  "updated_at": "2026-01-02T00:00:00.000Z",
  "deleted_at": null
}
```

Creating a contact triggers the organization's "contact created" automations.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `owned_by_user_id` is not a member of the organization, a custom field key is unknown, or a custom field value does not match its type. |
| `403 Forbidden` | `organization_id` is missing or not accessible with your key. |

<a id="contacts--update"></a>

### Update a contact

Source: https://www.achieveapex.com/docs/api-reference/contacts/update

Partially updates a contact. Only the fields you send change.

#### Endpoint

`PATCH /contacts/:id`

#### Body

Any writable field of the [contact object](#contacts). Unknown fields are rejected.

- `custom_fields_by_key` is merged with the existing values: only the keys you send change. Send a key with `null` to clear it. `custom_fields_by_name` and `custom_fields_meta_data` are rebuilt automatically.
- Changing any `*_blacklist` field (Do Not Disturb) sets `dnd_updated_at` to now and `dnd_source` to `manual` unless you send them.
- `phone` is normalized the same way as on create.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/contacts/123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.updated@example.com",
    "whatsapp_blacklist": true,
    "whatsapp_blacklist_reason": "Asked not to be contacted",
    "custom_fields_by_key": { "industry": "Finance" }
  }'
```

#### Response

Returns the updated [contact object](#contacts).

```json
{
  "id": 123,
  "organization_id": 456,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.updated@example.com",
  "whatsapp_blacklist": true,
  "whatsapp_blacklist_reason": "Asked not to be contacted",
  "dnd_updated_at": "2026-01-03T10:00:00.000Z",
  "dnd_source": "manual",
  "custom_fields_by_key": { "industry": "Finance" },
  "custom_fields_by_name": { "Industry": "Finance" },
  "updated_at": "2026-01-03T10:00:00.000Z",
  "deleted_at": null
}
```

The response contains the full contact; it is shortened here. Updating a contact triggers the organization's "contact updated" automations and refreshes the contact data shown on its conversations.

<a id="contacts--delete"></a>

### Delete a contact

Source: https://www.achieveapex.com/docs/api-reference/contacts/delete

Deletes a contact. This is a soft delete: the contact gets a `deleted_at` timestamp and no longer appears in list, get or search. The contact's conversations are soft-deleted too.

#### Endpoint

`DELETE /contacts/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/contacts/123 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [contact object](#contacts) with `deleted_at` set.

```json
{
  "id": 123,
  "organization_id": 456,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "updated_at": "2026-01-04T00:00:00.000Z",
  "deleted_at": "2026-01-04T00:00:00.000Z"
}
```

<a id="contacts--errors"></a>

### Contacts errors

Source: https://www.achieveapex.com/docs/api-reference/contacts/errors

Errors use the standard Feathers error format.

```json
{
  "name": "BadRequest",
  "message": "Invalid custom field keys: industy",
  "code": 400,
  "className": "bad-request"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query: wrong field type, unknown field on update, invalid custom field key or value, owner not in the organization, missing search parameters. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, or the record belongs to an organization the key cannot access. |
| `404 Not Found` | The contact does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error. |

<a id="contacts--search"></a>

### Search contacts

Source: https://www.achieveapex.com/docs/api-reference/contacts/search

Searches contacts of one organization by name, phone, email or a custom field. Same matching as `searchTerm` on [List contacts](#contacts--list), but the parameters go in a JSON body.

#### Endpoint

`POST /contacts` with header `X-Service-Method: search`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to search in. |
| `searchTerm` | string | Yes | Text to find (at least 3 characters). Without it the call returns no results. |
| `searchIn` | string | Yes | `all`, `name`, `phone`, `email` or `custom_field`. |
| `custom_field_name` | string | With `searchIn=custom_field` | Name of the custom field to search in. |
| `system_type` | string | No | Only `lead`, `contact` or `conversation` records. |
| `owned_by_user_id` | integer | No | Only contacts owned by this user. |
| `$limit` | integer | No | Page size. Default 10. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort` | object | No | One of `first_name`, `last_name`, `email`, `created_at`, `updated_at` with `1` or `-1`. Default `{ "first_name": 1 }`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Service-Method: search" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "searchTerm": "jane",
    "searchIn": "name",
    "$limit": 10
  }'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 124,
      "organization_id": 456,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone_country_code": "+1",
      "phone": "2025550199",
      "system_type": "contact",
      "deleted_at": null
    }
  ]
}
```

Each item is a full [contact object](#contacts); it is shortened here.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `organization_id` or `searchIn` is missing, `searchIn` is not a valid value, or `custom_field_name` is missing for `searchIn=custom_field`. |

---

## Conversation files

<a id="conversation-files"></a>

### Conversation files overview

Source: https://www.achieveapex.com/docs/api-reference/conversation-files

A conversation file is the record of an attachment uploaded to a conversation (image, audio, video or document). Register the file after uploading it, then reference it when you [send a message](#conversation-messages--send).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/conversation-files` | [Upload a file](#conversation-files--upload) |
| `GET` | `/conversation-files` | [List files](#conversation-files--list) |
| `GET` | `/conversation-files/:id` | [Get a file](#conversation-files--get) |

#### The conversation file object

```json
{
  "_id": "65e0a1b2c3d4e5f6a7b8c9d0",
  "organization_id": 456,
  "conversation_id": 5001,
  "file_name": "photo.jpg",
  "file_type": "image/jpeg",
  "file_size": 245678,
  "file_category": "image",
  "s3_key": "org_456/conversation_5001/20260210T150000_photo.jpg",
  "s3_path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_photo.jpg",
  "upload_by_user_id": 12,
  "uploaded_at": "2026-02-10T15:00:02.000Z",
  "updated_at": "2026-02-10T15:00:02.000Z"
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `_id` | string | Read-only. File ID. Send it as `conversation_file_id` with the message. |
| `organization_id` | integer | Read-only. Taken from the conversation. |
| `conversation_id` | integer | Conversation the file belongs to. Required. |
| `file_name` | string | Original file name. Required. |
| `file_type` | string | MIME type, e.g. `image/jpeg`. Required. |
| `file_size` | integer | Size in bytes. Required. |
| `file_category` | string | `image`, `audio`, `video` or `file`. Required. |
| `s3_key` | string | Storage key (`s3PathWithoutBucket` from the upload URL). |
| `s3_path` | string | Full `s3://` path (`s3Path` from the upload URL). |
| `upload_by_user_id` | integer \| null | Read-only. User who registered the file (the API key's user). |
| `uploaded_at` | string (date-time) | Read-only. Registration time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |

#### Related

- [Upload URLs](#s3-url-signing)
- [Send a message](#conversation-messages--send)

<a id="conversation-files--list"></a>

### List files

Source: https://www.achieveapex.com/docs/api-reference/conversation-files/list

List the files registered on a conversation, for example to build a media gallery of a thread.

#### Endpoint

`GET /conversation-files`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | No | Files of one conversation. |
| `file_category` | string | No | `image`, `audio`, `video` or `file`. |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[uploaded_at]` | `1` \| `-1` | No | Sort order. |

Results are limited to your API key's organization.

#### Request

```bash
curl -G https://integrations.achieveapex.com/conversation-files \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'conversation_id=5001' \
  --data-urlencode 'file_category=image' \
  --data-urlencode '$sort[uploaded_at]=-1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "_id": "65e0a1b2c3d4e5f6a7b8c9d0",
      "organization_id": 456,
      "conversation_id": 5001,
      "file_name": "photo.jpg",
      "file_type": "image/jpeg",
      "file_size": 245678,
      "file_category": "image",
      "s3_key": "org_456/conversation_5001/20260210T150000_photo.jpg",
      "s3_path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_photo.jpg",
      "upload_by_user_id": 12,
      "uploaded_at": "2026-02-10T15:00:02.000Z"
    }
  ]
}
```

See [The conversation file object](#conversation-files).

<a id="conversation-files--get"></a>

### Get a file

Source: https://www.achieveapex.com/docs/api-reference/conversation-files/get

Retrieve one conversation file by its `_id`.

#### Endpoint

`GET /conversation-files/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | File `_id`. |

#### Request

```bash
curl https://integrations.achieveapex.com/conversation-files/65e0a1b2c3d4e5f6a7b8c9d0 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "_id": "65e0a1b2c3d4e5f6a7b8c9d0",
  "organization_id": 456,
  "conversation_id": 5001,
  "file_name": "photo.jpg",
  "file_type": "image/jpeg",
  "file_size": 245678,
  "file_category": "image",
  "s3_key": "org_456/conversation_5001/20260210T150000_photo.jpg",
  "s3_path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_photo.jpg",
  "upload_by_user_id": 12,
  "uploaded_at": "2026-02-10T15:00:02.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The file does not exist or belongs to an organization your API key cannot access. |

<a id="conversation-files--upload"></a>

### Upload a file

Source: https://www.achieveapex.com/docs/api-reference/conversation-files/upload

Upload an attachment for an outgoing message in three steps: get a signed upload URL, `PUT` the bytes to it, then register the file on the conversation. Finally send the message with the file fields.

#### Endpoint

`POST /conversation-files`

#### Step 1: Get a signed upload URL

```bash
curl -X POST https://integrations.achieveapex.com/s3-url-signing \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "conversation-file",
    "filename": "photo.jpg",
    "conversation_id": 5001,
    "contentType": "image/jpeg"
  }'
```

```json
{
  "signedUrl": "https://achieveapex-conversation-files.s3.amazonaws.com/org_456/conversation_5001/20260210T150000_photo.jpg?X-Amz-Algorithm=...",
  "s3Path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_photo.jpg",
  "s3PathWithoutBucket": "org_456/conversation_5001/20260210T150000_photo.jpg",
  "headers": { "Content-Type": "image/jpeg" }
}
```

See [Create an upload URL](#s3-url-signing--create). The URL is valid for 1 hour.

#### Step 2: Upload the bytes

```bash
curl -X PUT "SIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg
```

Send the same `Content-Type` you passed as `contentType` in step 1.

#### Step 3: Register the file

##### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | Yes | Conversation receiving the file. |
| `file_name` | string | Yes | Original file name. |
| `file_type` | string | Yes | MIME type. |
| `file_size` | integer | Yes | Size in bytes. |
| `file_category` | string | Yes | `image`, `audio`, `video` or `file`. |
| `s3_key` | string | Yes | `s3PathWithoutBucket` from step 1. |
| `s3_path` | string | Yes | `s3Path` from step 1. |
| `organization_id` | integer | No | If sent, it must match the conversation's organization. The conversation's organization is always used. |

##### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversation-files \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 5001,
    "file_name": "photo.jpg",
    "file_type": "image/jpeg",
    "file_size": 245678,
    "file_category": "image",
    "s3_key": "org_456/conversation_5001/20260210T150000_photo.jpg",
    "s3_path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_photo.jpg"
  }'
```

##### Response

The [conversation file](#conversation-files) with its `_id`:

```json
{
  "_id": "65e0a1b2c3d4e5f6a7b8c9d0",
  "organization_id": 456,
  "conversation_id": 5001,
  "file_name": "photo.jpg",
  "file_type": "image/jpeg",
  "file_size": 245678,
  "file_category": "image",
  "s3_key": "org_456/conversation_5001/20260210T150000_photo.jpg",
  "s3_path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_photo.jpg",
  "upload_by_user_id": 12,
  "uploaded_at": "2026-02-10T15:00:02.000Z"
}
```

For Instagram conversations, images in unsupported formats are converted, and for WhatsApp conversations videos are re-encoded when WhatsApp would reject them; the stored `s3_key`, `file_name` and `file_type` can therefore differ from what you sent. Use the values in the response.

#### Step 4: Send the message

Pass `s3_key`, `file_name`, `file_type`, `file_size` and `conversation_file_id` (the `_id`) to [Send a message](#conversation-messages--send) with `message_type` `image`, `video`, `audio` or `document`. For SMS, send the public URL `https://achieveapex-conversation-files.s3.amazonaws.com/<s3_key>` in `media_urls`.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `conversation_id` missing or not found, `organization_id` does not match the conversation, or a required field is missing. |

---

## Conversation messages

<a id="conversation-messages"></a>

### Conversation messages overview

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages

Messages of a [conversation](#conversations). Each channel has its own message service: read the conversation's `channel` and use the matching path. Customer-facing messages on Meta channels and webchat are **sent** through an "outgoing" service that builds the channel payload and then stores the message; SMS and playground messages are sent directly on their message service.

#### Endpoints

| `channel` | List / get / edit note / delete | Send |
|---|---|---|
| `whatsapp` | `GET /conversation-messages-whatsapp` | `POST /conversation-messages-transform-outgoing-whatsapp` |
| `instagram` | `GET /conversation-messages-instagram` | `POST /conversation-messages-transform-outgoing-instagram` |
| `messenger` | `GET /conversation-messages-messenger` | `POST /conversation-messages-transform-outgoing-messenger` |
| `webchat` | `GET /conversation-messages-webchat` | `POST /conversation-messages-transform-outgoing-webchat` |
| `sms` | `GET /conversation-messages-sms` | `POST /conversation-messages-sms` |
| `playground` | `GET /conversation-messages-playground` | `POST /conversation-messages-playground` |

| Operation | Page |
|---|---|
| List messages of a conversation | [List messages](#conversation-messages--list) |
| Get one message | [Get a message](#conversation-messages--get) |
| Send text, media, location or an internal note | [Send a message](#conversation-messages--send) |
| Send a WhatsApp template | [Send a WhatsApp template](#conversation-messages--send-whatsapp-template) |
| Edit an internal note | [Edit a note](#conversation-messages--update) |
| Delete a message | [Delete a message](#conversation-messages--delete) |

Attachments are uploaded first with [Conversation files](#conversation-files--upload).

#### The message object

A WhatsApp message (other channels share the same core fields):

```json
{
  "_id": "65d1c0a1b2c3d4e5f6a7b8c9",
  "conversation_id": 5001,
  "organization_id": 456,
  "contact_id": 88001,
  "message_type": "text",
  "message_text": "Your order has shipped.",
  "destination": "outgoing",
  "message_id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAERgS",
  "whatsapp_status": "delivered",
  "read": false,
  "timestamp": "2026-02-10T15:22:00.000Z",
  "meta_contact_first_name": "Maria",
  "meta_contact_last_name": "Lopez",
  "meta_contact_avatar_url": null,
  "meta_contact_channel_wa_user_id": null,
  "user_id": 12,
  "meta_user_first_name": "Carlos",
  "meta_user_last_name": "Ruiz",
  "meta_user_avatar_url": null,
  "meta_user_role": "user",
  "ai_assistant_id": null,
  "ai_assistant_name": null,
  "automation_id": null,
  "automation_name": null,
  "created_at": "2026-02-10T15:22:00.000Z",
  "updated_at": "2026-02-10T15:22:05.000Z",
  "deleted_at": null
}
```

#### Fields

IDs: messages of WhatsApp, Instagram, Messenger, webchat and SMS have a string `_id`; playground messages have an integer `id`. The "Channels" column says where a field appears (blank = all channels).

| Field | Type | Channels | Description |
|---|---|---|---|
| `_id` | string | all but playground | Read-only. Message ID. |
| `id` | integer | playground | Read-only. Message ID. |
| `conversation_id` | integer | | Conversation of the message. |
| `organization_id` | integer | | Organization. |
| `contact_id` | integer \| null | | Contact of the conversation. |
| `message_type` | string | | `text`, `image`, `video`, `audio`, `document`, `file`, `sticker`, `location`, `contacts`, `template`, `note` (internal note), `reaction`, `system`, `error`, `unsupported`, tool/automation events (`internal_tool`, `api_tool`, `mcp_tool`, `skill_reading`, `automation_started`, `automation_completed`, `automation_failed`), Instagram `ig_post` / `ig_reel`. SMS: `text`, `image`, `video`, `audio`, `document`, `media`, `template`, `reaction`, `note`. |
| `message_text` | string \| null | | Message text or media caption. |
| `text` | string | | Text copy used by SMS, webchat and playground (`message_text` mirrors it). On SMS, `text` is the field you send. |
| `destination` | string | | `incoming` (from the contact), `outgoing` (to the contact), `internal` (note, WhatsApp/Instagram/Messenger/webchat) or `system`. |
| `role` | string \| null | playground | `user` for messages you send as the contact. |
| `message_id` | string | | Channel message ID (for example the WhatsApp `wamid`). |
| `whatsapp_status` | string | whatsapp | Delivery status reported by WhatsApp: `sent`, `delivered`, `read`, or `failed`. |
| `messenger_status` | string | messenger | Delivery status reported by Messenger, e.g. `sent`. |
| `delivery_status` | string \| null | sms | `queued`, `sent`, `delivered`, `failed` or `received`. |
| `status` | string \| null | playground | Message status. |
| `read` | boolean | | Whether the message was read in the inbox. Default `false`. |
| `timestamp` | string \| null | | Channel timestamp of the message. |
| `media_url` | string | | URL of the image, audio, video or document. |
| `media_urls` | string[] \| null | sms | Media URLs of an MMS. |
| `filename` | string | | Original file name of the attachment. |
| `file_name` | string | webchat, playground | Original file name of the attachment. |
| `mime_type` | string | | MIME type of the attachment. |
| `file_type` | string \| null | playground | MIME type of the attachment. |
| `file_size` | integer | webchat, playground | Attachment size in bytes. |
| `s3_key` / `s3_path` | string \| null | playground | Storage key and `s3://` path of the attachment. |
| `conversation_file_id` | string | webchat, playground | [Conversation file](#conversation-files) of the attachment. |
| `location_latitude` / `location_longitude` | string \| number | whatsapp, instagram | Location messages: coordinates. |
| `location_name` / `location_address` | string | whatsapp, instagram | Location messages: place name and address. |
| `revoked` | boolean \| null | whatsapp | The contact deleted the message in WhatsApp. |
| `edited` | boolean \| null | whatsapp | The message was edited (by the contact in WhatsApp, or an edited internal note). |
| `message_text_original` | string \| null | whatsapp | Text before the edit. |
| `order_data` | object \| null | whatsapp | WhatsApp catalog order sent by the contact. |
| `interactive_data` | object \| null | whatsapp | Interactive reply (list or button) sent by the contact. |
| `interactive_type` | string \| null | whatsapp | Type of the interactive reply. |
| `button_data` | object \| null | whatsapp | Quick-reply button pressed by the contact. |
| `campaign_id` | integer \| null | whatsapp, sms | Campaign that sent the message. |
| `is_bulk` | boolean | sms | Sent by a bulk SMS campaign. |
| `is_echo` | boolean | whatsapp, instagram, sms | `true` on an outgoing message that was not sent from AchieveApex (the native app, Meta Business Suite, the WhatsApp Business app or a third-party tool) and was reported back by the provider. |
| `is_history` | boolean | whatsapp | Message imported from the WhatsApp Business app history when the number was connected. |
| `from` / `to` | string \| null | sms | Sender and recipient phone numbers. |
| `error_code` / `error_message` | string \| null | sms | Provider error when the SMS failed. |
| `error` | object \| null | | Error details when sending or the AI reply failed. |
| `contact_deleted` | boolean \| null | sms | The contact was deleted. |
| `meta_contact_first_name` / `meta_contact_last_name` | string \| null | | Contact name at the time of the message. |
| `meta_contact_avatar_url` | string \| null | | Contact avatar. |
| `meta_contact_phone` | string \| null | sms | Contact phone. |
| `meta_contact_channel_wa_user_id` | string \| null | whatsapp | Contact's WhatsApp Business-Scoped User ID, when Meta sent one. |
| `user_id` | integer \| null | | Team member who sent the message. |
| `meta_user_first_name` / `meta_user_last_name` | string \| null | | Sender name. |
| `meta_user_avatar_url` | string \| null | | Sender avatar. |
| `meta_user_role` | string \| null | | Sender platform role. |
| `ai_assistant_id` | integer \| null | | AI assistant that wrote the message. |
| `ai_assistant_name` | string \| null | | Name of that assistant. |
| `ai_model` | object \| null | all but sms | Model used for the AI reply. |
| `ai_structured_data` | object \| null | all but sms | Structured output returned with the AI reply. |
| `automation_id` / `automation_name` | integer / string \| null | | Automation that sent the message. |
| `automation_execution_id` | integer \| null | | [Automation execution](#automations-executions) that sent it. |
| `is_from_automation` | boolean \| null | playground | Sent by an automation. |
| `follow_up_details` | object \| null | | Details of an AI follow-up message. |
| `change_metadata` | object \| null | | Details of a system message that records a change (assignment, stage, ...). |
| `tool_metadata` | object \| null | | Details of an AI tool call message. |
| `created_at` | string (date-time) | | Read-only. Creation time. |
| `updated_at` | string (date-time) | | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | | Read-only. Set when the message is deleted. |

Messages can carry extra channel data (for example Instagram story replies, WhatsApp ad referrals or quoted replies in `replied_to_message`). Treat unknown fields as optional.

<a id="conversation-messages--list"></a>

### List messages

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages/list

Load the message history of a conversation. Call the message service that matches the conversation's `channel`.

#### Endpoint

`GET /conversation-messages-whatsapp`

Same request for every channel:

- `GET /conversation-messages-instagram`
- `GET /conversation-messages-messenger`
- `GET /conversation-messages-webchat`
- `GET /conversation-messages-sms`
- `GET /conversation-messages-playground`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | Yes | Conversation to load. Always send it. |
| `message_type[$ne]` | string | No | `message_type[$ne]=reaction` hides reaction rows, like the inbox does. |
| `destination` | string | No | `incoming`, `outgoing`, `internal` or `system`. |
| `created_at[$gte]` / `created_at[$lte]` | string (date-time) | No | Date range. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Records to skip. |
| `$sort[created_at]` | `1` \| `-1` | No | `-1` = newest first (reverse it for chronological display). |

Any other [message field](#conversation-messages) can be used as a filter.

#### Request

```bash
curl -G https://integrations.achieveapex.com/conversation-messages-whatsapp \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'conversation_id=5001' \
  --data-urlencode 'message_type[$ne]=reaction' \
  --data-urlencode '$sort[created_at]=-1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 120,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "_id": "65d1c0a1b2c3d4e5f6a7b8c9",
      "conversation_id": 5001,
      "organization_id": 456,
      "message_type": "text",
      "message_text": "Hello! Is my order ready?",
      "destination": "incoming",
      "read": true,
      "created_at": "2026-02-10T10:00:00.000Z"
    }
  ]
}
```

Fields are described in [The message object](#conversation-messages).

#### Notes

- Deleted messages are not returned.
- Members restricted to some channel accounts get `403 Forbidden` for conversations of accounts they cannot see.

<a id="conversation-messages--get"></a>

### Get a message

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages/get

Retrieve one message by its ID from the message service of the conversation's channel.

#### Endpoint

`GET /conversation-messages-whatsapp/:id`

Same request for every channel:

- `GET /conversation-messages-instagram/:id`
- `GET /conversation-messages-messenger/:id`
- `GET /conversation-messages-webchat/:id`
- `GET /conversation-messages-sms/:id`
- `GET /conversation-messages-playground/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string \| integer | Yes | The message `_id` (string). Playground messages use the integer `id`. |

#### Request

```bash
curl https://integrations.achieveapex.com/conversation-messages-whatsapp/65d1c0a1b2c3d4e5f6a7b8c9 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "_id": "65d1c0a1b2c3d4e5f6a7b8c9",
  "conversation_id": 5001,
  "organization_id": 456,
  "contact_id": 88001,
  "message_type": "image",
  "message_text": "Here is the photo",
  "destination": "outgoing",
  "media_url": "https://achieveapex-conversation-files.s3.amazonaws.com/org_456/conversation_5001/20260210T150000_photo.jpg",
  "mime_type": "image/jpeg",
  "filename": "photo.jpg",
  "whatsapp_status": "read",
  "created_at": "2026-02-10T15:00:00.000Z"
}
```

See [The message object](#conversation-messages).

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The message does not exist or was deleted. |

<a id="conversation-messages--update"></a>

### Edit a note

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages/update

Rewrite the text of an internal note (`message_type: note`). Only notes can be edited through the API; customer messages cannot be changed.

#### Endpoint

`PATCH /conversation-messages-whatsapp/:id`

Same request for every channel:

- `PATCH /conversation-messages-instagram/:id`
- `PATCH /conversation-messages-messenger/:id`
- `PATCH /conversation-messages-webchat/:id`
- `PATCH /conversation-messages-playground/:id`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `message_text` | string | Yes | New note text. 1 to 20,000 characters. |

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/conversation-messages-whatsapp/65d1c0a1b2c3d4e5f6a7b8ca \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_text": "Customer prefers a call after 6pm." }'
```

#### Response

The updated [message](#conversation-messages). On every channel except playground, `edited` becomes `true` and `message_text_original` keeps the first text.

```json
{
  "_id": "65d1c0a1b2c3d4e5f6a7b8ca",
  "conversation_id": 5001,
  "message_type": "note",
  "destination": "internal",
  "message_text": "Customer prefers a call after 6pm.",
  "text": "Customer prefers a call after 6pm.",
  "edited": true,
  "message_text_original": "Customer prefers a call after 5pm.",
  "updated_at": "2026-02-10T18:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | The text is empty or too long, the message is not a note, or it was deleted. |

<a id="conversation-messages--delete"></a>

### Delete a message

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages/delete

Delete one message from the inbox. This is a soft delete: the message gets `deleted_at` and stops appearing in list and get responses. It is **not** deleted from the contact's WhatsApp, Instagram, Messenger or phone.

#### Endpoint

`DELETE /conversation-messages-whatsapp/:id`

Same request for every channel:

- `DELETE /conversation-messages-instagram/:id`
- `DELETE /conversation-messages-messenger/:id`
- `DELETE /conversation-messages-webchat/:id`
- `DELETE /conversation-messages-sms/:id`
- `DELETE /conversation-messages-playground/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string \| integer | Yes | Message `_id` (integer `id` for playground). |

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/conversation-messages-whatsapp/65d1c0a1b2c3d4e5f6a7b8c9 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [message](#conversation-messages) with `deleted_at` set. If the message was pinned on the conversation it is unpinned.

```json
{
  "_id": "65d1c0a1b2c3d4e5f6a7b8c9",
  "conversation_id": 5001,
  "message_type": "text",
  "deleted_at": "2026-02-10T18:10:00.000Z"
}
```

<a id="conversation-messages--send"></a>

### Send a message

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages/send

Send a message to the contact of a conversation, or store an internal note. Use the send service of the conversation's `channel`.

#### Endpoint

`POST /conversation-messages-transform-outgoing-whatsapp`

| `channel` | Send with |
|---|---|
| `whatsapp` | `POST /conversation-messages-transform-outgoing-whatsapp` |
| `instagram` | `POST /conversation-messages-transform-outgoing-instagram` |
| `messenger` | `POST /conversation-messages-transform-outgoing-messenger` |
| `webchat` | `POST /conversation-messages-transform-outgoing-webchat` |
| `sms` | `POST /conversation-messages-sms` ([see below](#sms)) |
| `playground` | `POST /conversation-messages-playground` ([see below](#playground)) |

#### WhatsApp, Instagram, Messenger and webchat

The organization, contact and channel identifiers are taken from the conversation; you only send the content. The sender is the API key's user.

##### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | Yes | Conversation to write in. |
| `message_type` | string | Yes | See the table below. `note` stores an internal note (`destination: internal`) that the contact never sees. |
| `message_text` | string | For `text` and `note` | Text, or the caption of a media message. |
| `s3_key` | string | For media | Key of the uploaded file (`s3PathWithoutBucket` from [Upload a file](#conversation-files--upload)). |
| `file_name` | string | For media | Original file name. |
| `file_type` | string | For media | MIME type, e.g. `image/jpeg`. |
| `file_size` | integer | No | Size in bytes. |
| `conversation_file_id` | string | No | `_id` of the [conversation file](#conversation-files). |
| `location` | object | For `location` | `{ "latitude", "longitude", "name", "address" }`. Latitude and longitude are required. |
| `replied_to_message_id` | string | No | WhatsApp: `_id` of a message of the conversation to quote (reply to). Ignored for notes. |

##### Message types per channel

| `message_type` | WhatsApp | Instagram | Messenger | Webchat |
|---|---|---|---|---|
| `text` | yes | yes | yes | yes |
| `note` | yes | yes | yes | no (webchat messages do not accept the `internal` destination) |
| `image`, `video`, `audio` | yes | yes | yes | yes |
| `document` | yes | yes | no | yes |
| `file` | yes | no | no | no |
| `location` | yes | yes | no | yes |
| `template` | [WhatsApp templates](#conversation-messages--send-whatsapp-template) | no | no | no |

##### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-transform-outgoing-whatsapp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 5001,
    "message_type": "text",
    "message_text": "Your order has shipped."
  }'
```

Image with caption (after [uploading the file](#conversation-files--upload)):

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-transform-outgoing-whatsapp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 5001,
    "message_type": "image",
    "message_text": "Here is the photo you asked for.",
    "s3_key": "org_456/conversation_5001/20260210T150000_photo.jpg",
    "file_name": "photo.jpg",
    "file_type": "image/jpeg",
    "file_size": 245678,
    "conversation_file_id": "65e0a1b2c3d4e5f6a7b8c9d0"
  }'
```

Internal note:

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-transform-outgoing-instagram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "conversation_id": 6001, "message_type": "note", "message_text": "Customer prefers a call after 5pm." }'
```

Location:

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-transform-outgoing-whatsapp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 5001,
    "message_type": "location",
    "location": { "latitude": "4.6097", "longitude": "-74.0817", "name": "Main store", "address": "Cra 7 #12-34, Bogota" }
  }'
```

##### Response

The stored [message](#conversation-messages):

```json
{
  "_id": "65d1c0a1b2c3d4e5f6a7b8c9",
  "conversation_id": 5001,
  "organization_id": 456,
  "contact_id": 88001,
  "message_type": "text",
  "message_text": "Your order has shipped.",
  "destination": "outgoing",
  "message_id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAERgS",
  "user_id": 12,
  "meta_user_first_name": "Carlos",
  "created_at": "2026-02-10T15:22:00.000Z"
}
```

##### Rules

- **24-hour window:** WhatsApp, Instagram and Messenger only accept free-form messages within 24 hours of the contact's last message. Outside it, WhatsApp needs a [template](#conversation-messages--send-whatsapp-template). Notes are always allowed.
- **Do not disturb / blacklist:** a contact blacklisted for WhatsApp returns `403 Forbidden`; Instagram and Messenger respect the contact's do-not-disturb setting for the channel.
- WhatsApp messages go out from the conversation's number (`whatsapp_channel_id`).

#### SMS

`POST /conversation-messages-sms` stores the message and, when `destination` is `outgoing`, sends it.

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | Yes | SMS conversation. |
| `organization_id` | integer | Yes | Your organization ID. |
| `text` | string | Yes | Message text (can be `""` for an MMS with media only). |
| `destination` | string | Yes, to send | `outgoing`. The default is `incoming`, which stores the message without sending it. |
| `message_type` | string | No | `text` (default), or `image` / `video` / `audio` / `document` with media. |
| `media_urls` | string[] | No | Public URLs of the media to send as MMS. |
| `media_url`, `mime_type`, `filename` | string | No | Media shown in the inbox. |
| `from` / `to` | string | No | Default to the conversation's `our_phone_number` and `contact_phone`. |

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 7001,
    "organization_id": 456,
    "text": "We are running 10 minutes late.",
    "message_type": "text",
    "destination": "outgoing"
  }'
```

The response is the stored message with `delivery_status: "queued"`, or `"failed"` with `error_message` when the provider rejected it. Phone numbers on the organization's SMS blacklist are rejected.

#### Playground

`POST /conversation-messages-playground` writes in an AI assistant playground conversation (`channel: playground`, see [Create a conversation](#conversations--create)). A message with `destination: incoming` acts as the contact and the conversation's AI assistant replies in the thread; read the reply with [List messages](#conversation-messages--list).

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | Yes | Playground conversation. |
| `organization_id` | integer | Yes | Your organization ID. |
| `message_type` | string | Yes | `text`, or a media type with the file fields below. |
| `destination` | string | Yes | `incoming` to talk as the contact. |
| `text` or `message_text` | string | Yes | Message text (one is copied to the other). |
| `contact_id` | integer | No | Contact of the conversation. |
| `role` | string | No | `user`. |
| `s3_key`, `s3_path`, `file_name`, `file_type`, `file_size`, `conversation_file_id` | | No | Attachment fields (`media_url` is built from `s3_key`). |

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-playground \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 5100,
    "organization_id": 456,
    "contact_id": 88001,
    "message_type": "text",
    "text": "Do you ship to Medellin?",
    "destination": "incoming",
    "role": "user"
  }'
```

Unknown fields are rejected on the playground service.

#### Errors

| Status | When |
|---|---|
| `400` / `500` | `conversation_id` or `message_type` missing, the conversation does not exist, a media message without `s3_key`, or the channel rejected the message. |
| `403 Forbidden` | The contact is blacklisted for the channel. |

<a id="conversation-messages--send-whatsapp-template"></a>

### Send a WhatsApp template

Source: https://www.achieveapex.com/docs/api-reference/conversation-messages/send-whatsapp-template

Send an approved WhatsApp template in a WhatsApp conversation. Templates are the only way to write to a contact outside WhatsApp's 24-hour window (for example right after [starting a conversation](#conversations--initiate-whatsapp)).

#### Endpoint

`POST /conversation-messages-transform-outgoing-whatsapp`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `conversation_id` | integer | Yes | WhatsApp conversation. |
| `message_type` | string | Yes | `template`. |
| `template_id` | integer | Yes | `id` of the template from [List WhatsApp templates](#whatsapp-channel-message-templates--list). Must belong to your organization. WhatsApp only delivers templates with status `APPROVED`. |
| `custom_variables` | object | No | Values for template placeholders, keyed by the variable names in the template's `variables_matching` (for example `{ "custom_body_1": "A-1043" }`). |

##### How placeholders are filled

Each template has `variables_matching`, which maps a placeholder (`body_1` = `{{1}}` of the body, `header_1` = `{{1}}` of the header) to a variable name. When sending, each variable is filled from `custom_variables`, the contact's data (for example `contact_first_name`, `contact_full_name`), the contact's custom fields, or the conversation owner's fields. Templates imported from Meta map `{{n}}` to `custom_body_n` / `custom_header_n`, so pass those keys in `custom_variables`.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversation-messages-transform-outgoing-whatsapp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 5001,
    "message_type": "template",
    "template_id": 812,
    "custom_variables": {
      "custom_body_1": "A-1043",
      "custom_body_2": "Friday"
    }
  }'
```

#### Response

The stored [message](#conversation-messages), with `message_type: "template"` and the rendered text in `message_text`.

```json
{
  "_id": "65d1c0a1b2c3d4e5f6a7b8d1",
  "conversation_id": 5001,
  "organization_id": 456,
  "message_type": "template",
  "message_text": "Hi Maria, your order A-1043 arrives Friday.",
  "destination": "outgoing",
  "message_id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAERgT",
  "created_at": "2026-02-10T17:05:00.000Z"
}
```

#### Notes

- A template can only be sent from a number of its own WhatsApp Business Account (WABA). If the conversation's number is in another WABA, the template with the same name and language of that WABA is used; if there is none the request is rejected.
- Contacts blacklisted for WhatsApp return `403 Forbidden`.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | The template belongs to another organization or cannot be sent from the conversation's number. |
| `404 Not Found` | `template_id` does not exist. |

---

## Conversations

<a id="conversations"></a>

### Conversations overview

Source: https://www.achieveapex.com/docs/api-reference/conversations

A conversation is one chat thread between your organization and a contact on one channel (WhatsApp, Instagram, Messenger, webchat, SMS or the AI assistant playground). Use it to list and filter your inbox, assign owners and AI assistants, move threads through pipelines, and close or reopen them. Messages live in [Conversation messages](#conversation-messages).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/conversations` | [List conversations](#conversations--list) |
| `GET` | `/conversations/:id` | [Get a conversation](#conversations--get) |
| `POST` | `/conversations` | [Create a conversation](#conversations--create) |
| `PATCH` | `/conversations/:id` | [Update a conversation](#conversations--patch) |
| `DELETE` | `/conversations/:id` | [Delete a conversation](#conversations--delete) |
| `POST` | `/conversation-initiate-whatsapp` | [Start a WhatsApp conversation](#conversations--initiate-whatsapp) |
| `POST` | `/conversations-bulk-actions` | [Run a bulk action](#conversations--bulk-actions) |
| `GET` | `/conversations-bulk-actions` | [List bulk actions](#conversations--bulk-actions-list) |
| `GET` | `/conversations-bulk-actions/:id` | [Get a bulk action](#conversations--bulk-actions-get) |

#### The conversation object

```json
{
  "id": 5001,
  "organization_id": 456,
  "channel": "whatsapp",
  "contact_id": 88001,
  "whatsapp_channel_id": 12,
  "contact_phone": null,
  "our_phone_number": null,
  "voice_phone_number_id": null,
  "status": "open",
  "assigned_user_id": 12,
  "assigned_ai_assistant_id": 3,
  "pipeline_id": 10,
  "pipeline_stage_id": 55,
  "unread_count": 2,
  "blocked": false,
  "meta_contact_first_name": "Maria",
  "meta_contact_last_name": "Lopez",
  "meta_contact_channel_wa_id": "573001234567",
  "meta_contact_channel_wa_user_id": null,
  "meta_contact_channel_wa_username": null,
  "meta_contact_channel_wa_profile_name": "Maria Lopez",
  "meta_contact_channel_instagram_profile_name": null,
  "meta_contact_avatar_url": null,
  "meta_contact_tags": [{ "id": 7, "name": "VIP", "color": "#F59E0B" }],
  "last_message_received": "2026-02-10T15:20:00.000Z",
  "last_message_sent": "2026-02-10T15:22:00.000Z",
  "last_message_system": "2026-02-09T09:00:00.000Z",
  "last_interaction_at": "2026-02-10T15:22:00.000Z",
  "last_message_sent_preview": "Thanks, we will ship tomorrow.",
  "ai_context_cut": null,
  "ai_resume_instruction": null,
  "ai_resume_instruction_set_at": null,
  "handoff_reason": null,
  "next_follow_up_rule_id": null,
  "next_follow_up_date_time": null,
  "follow_up_count": 0,
  "last_ai_response_at": "2026-02-10T15:22:00.000Z",
  "token_limit_reached_at": null,
  "token_limit_reason": null,
  "ai_auto_assignment_disabled": false,
  "ai_auto_assignment_disabled_reason": null,
  "conversation_summary": null,
  "conversation_summary_updated_at": null,
  "pinned_messages": [],
  "created_at": "2026-02-01T09:00:00.000Z",
  "updated_at": "2026-02-10T15:22:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the conversation. Required on create. |
| `channel` | string | One of `whatsapp`, `instagram`, `messenger`, `webchat`, `playground`, `sms`. Required on create. Decides which [message service](#conversation-messages) holds its messages. |
| `contact_id` | integer | [Contact](#contacts) on the other side. Required on create. |
| `whatsapp_channel_id` | integer \| null | WhatsApp conversations: the [WhatsApp number](#whatsapp-channels) the thread belongs to. Messages always go out from this number. |
| `contact_phone` | string \| null | SMS conversations: the contact's phone number. |
| `our_phone_number` | string \| null | SMS conversations: your phone number used in the thread. |
| `voice_phone_number_id` | integer \| null | SMS conversations: ID of your phone number record used in the thread. |
| `status` | string | One of `open`, `closed`. Default `open`. |
| `assigned_user_id` | integer \| null | Human owner (a member of the organization). `null` = unassigned. |
| `assigned_ai_assistant_id` | integer \| null | [AI assistant](#ai-assistants) answering the thread. `null` = no AI. Must belong to the same organization. |
| `pipeline_id` | integer \| null | Conversation [pipeline](#pipelines) (type `conversation`). |
| `pipeline_stage_id` | integer \| null | [Stage](#pipeline-stages) inside `pipeline_id`. `null` = the pipeline's Incoming column. |
| `unread_count` | integer | Unread incoming messages. Default `0`. Set `0` to mark read, `1` to mark unread. |
| `blocked` | boolean | When `true`, incoming messages of the thread are ignored. Default `false`. |
| `meta_contact_first_name` | string | Contact first name copied onto the conversation (used by list and search). |
| `meta_contact_last_name` | string | Contact last name copied onto the conversation. |
| `meta_contact_channel_wa_id` | string \| null | WhatsApp: the contact's WhatsApp phone ID (digits with country code). |
| `meta_contact_channel_wa_user_id` | string \| null | WhatsApp: the contact's Business-Scoped User ID when Meta sends one instead of a phone number. |
| `meta_contact_channel_wa_username` | string \| null | WhatsApp: the contact's WhatsApp username, when known. |
| `meta_contact_channel_wa_profile_name` | string \| null | WhatsApp: the contact's WhatsApp profile name. |
| `meta_contact_channel_instagram_profile_name` | string \| null | Instagram: the contact's Instagram profile name. |
| `meta_contact_avatar_url` | string \| null | Contact avatar URL. |
| `meta_contact_tags` | array | Read-only copy of the contact's tags: `{ "id", "name", "color" }`. Filter with `tag_id` on [List](#conversations--list). |
| `last_message_received` | string (date-time) | Read-only. Time of the last incoming message. |
| `last_message_sent` | string (date-time) | Read-only. Time of the last outgoing message. |
| `last_message_system` | string (date-time) | Read-only. Time of the last system message. |
| `last_interaction_at` | string (date-time) | Read-only. Time of the last message in any direction. Sort the inbox by this field. |
| `last_message_sent_preview` | string \| null | Read-only. Preview text of the last message. |
| `ai_context_cut` | string (date-time) \| null | The AI assistant only reads messages after this time. Send any non-empty value in a `PATCH` to cut the context now (see [Update](#conversations--patch)). |
| `ai_resume_instruction` | string \| null | Read-only. Instruction the AI assistant follows on its next reply, set when an assistant is reassigned with a resume instruction in the app. |
| `ai_resume_instruction_set_at` | string (date-time) \| null | Read-only. When `ai_resume_instruction` was set. |
| `handoff_reason` | string \| null | Why the AI assistant handed the thread to a human. Cleared when the AI context is cut. |
| `next_follow_up_rule_id` | string \| null | Read-only. AI follow-up rule scheduled next. |
| `next_follow_up_date_time` | string \| null | When the next AI follow-up message is scheduled. Setting it schedules the follow-up. |
| `follow_up_count` | integer | Read-only. AI follow-ups already sent in the current cycle. Default `0`. |
| `last_ai_response_at` | string (date-time) \| null | Read-only. Time of the last AI assistant reply. |
| `token_limit_reached_at` | string (date-time) \| null | Read-only. When the AI safeguards stopped the assistant on this thread. Reset when you assign an AI assistant. |
| `token_limit_reason` | string \| null | Read-only. Why the AI safeguards stopped the assistant. |
| `ai_auto_assignment_disabled` | boolean | When `true`, automatic AI assignment rules skip this thread. Default `false`. Assigning an AI assistant resets it to `false`. |
| `ai_auto_assignment_disabled_reason` | string \| null | Reason stored with `ai_auto_assignment_disabled`. |
| `conversation_summary` | string \| null | Read-only. AI summary of older messages. Cleared when the AI context is cut. |
| `conversation_summary_updated_at` | string (date-time) \| null | Read-only. When `conversation_summary` was last written. |
| `pinned_messages` | array | Up to 3 pinned messages: `{ "message_id", "message_type", "preview", "destination", "pinned_at", "pinned_by_user_id" }`. Default `[]`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the conversation is deleted. |

Reads are limited to your API key's organization.

#### Related

- [Conversation messages](#conversation-messages): list, send and delete messages
- [Conversation files](#conversation-files): attachments
- [Predefined messages](#conversation-predefined-messages): canned replies
- [WhatsApp numbers](#whatsapp-channels) and [WhatsApp templates](#whatsapp-channel-message-templates)
- [Automation executions](#automations-executions): run an automation on a conversation
- [Pipelines](#pipelines) and [Pipeline stages](#pipeline-stages) (type `conversation`)

<a id="conversations--list"></a>

### List conversations

Source: https://www.achieveapex.com/docs/api-reference/conversations/list

List the conversations of your organization with filters, text search and pagination. This is the same query the inbox and the conversation pipeline board use.

#### Endpoint

`GET /conversations`

#### Query parameters

Any [conversation field](#conversations) can be used as a filter with the [standard operators](#requests). The ones below are the most useful, plus the extra search parameters this resource supports.

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization to list. Required when you use `messageSearchTerm`. |
| `status` | string | No | `open` or `closed`. |
| `channel` | string | No | One channel, e.g. `whatsapp`. Use `channel[$ne]=playground` to hide AI playground threads like the inbox does. |
| `channels` | string | No | Comma-separated list of channels and/or specific WhatsApp numbers: `whatsapp,instagram` or `whatsapp:12,sms` (`whatsapp:<whatsapp_channel_id>`). Matches any entry. |
| `assigned_user_id` | integer \| null | No | Human owner. `assigned_user_id=null` returns unassigned threads. |
| `assigned_ai_assistant_id` | integer \| null | No | AI assistant. `null` returns threads without AI. |
| `pipeline_id` | integer | No | Conversation pipeline. Only conversations of the channels the pipeline accepts are returned ([channel scope](https://www.achieveapex.com/docs/api-reference/pipelines/overview#channel-scope-conversation-pipelines)). |
| `pipeline_stage_id` | integer \| null | No | Stage. `null` returns threads without a stage. |
| `incoming_pipeline_id` | integer | No | Incoming column of one pipeline: threads with no stage that belong to that pipeline or to no pipeline. Overrides `pipeline_id` / `pipeline_stage_id`. Limited to the channels the pipeline accepts. |
| `whatsapp_channel_id` | integer | No | Threads of one WhatsApp number. |
| `contact_id` | integer | No | Threads of one contact. |
| `tag_id` | string | No | One contact tag ID or a comma-separated list (`7,12`). Matches threads whose contact has any of the tags. |
| `unread_count[$gt]` | integer | No | `unread_count[$gt]=0` returns unread threads only. |
| `waitingResponseOnly` | boolean | No | `true` returns threads whose last incoming message is newer than the last outgoing one. |
| `searchTerm` | string | No | Searches contact first/last/full name, WhatsApp profile name, WhatsApp phone ID, WhatsApp username and Instagram profile name. |
| `messageSearchTerm` | string | No | Searches message text (WhatsApp, Instagram, Messenger and webchat). At least 3 characters, otherwise ignored. Each result gets a `matchingMessages` array with one sample message. Pass `organization_id` with it. |
| `last_interaction_at[$gte]` / `created_at[$gte]` ... | string (date-time) | No | Date ranges with `$gte`, `$lte`. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[last_interaction_at]=-1` (newest activity first, like the inbox). |
| `$select[]` | string | No | Return only these fields, e.g. `$select[]=id`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/conversations \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'status=open' \
  --data-urlencode 'channel[$ne]=playground' \
  --data-urlencode 'assigned_user_id=12' \
  --data-urlencode 'unread_count[$gt]=0' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$sort[last_interaction_at]=-1'
```

Search by contact name inside one pipeline stage:

```bash
curl -G https://integrations.achieveapex.com/conversations \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'pipeline_id=10' \
  --data-urlencode 'pipeline_stage_id=55' \
  --data-urlencode 'searchTerm=Maria'
```

#### Response

```json
{
  "total": 240,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 5001,
      "organization_id": 456,
      "channel": "whatsapp",
      "contact_id": 88001,
      "whatsapp_channel_id": 12,
      "status": "open",
      "unread_count": 2,
      "assigned_user_id": 12,
      "assigned_ai_assistant_id": 3,
      "pipeline_id": 10,
      "pipeline_stage_id": 55,
      "meta_contact_first_name": "Maria",
      "meta_contact_last_name": "Lopez",
      "last_message_sent_preview": "Thanks, we will ship tomorrow.",
      "last_interaction_at": "2026-02-10T15:22:00.000Z",
      "created_at": "2026-02-01T09:00:00.000Z",
      "updated_at": "2026-02-10T15:22:00.000Z"
    }
  ]
}
```

Each item is a full [conversation object](#conversations) (shortened here).

#### Notes

- Results are limited to your API key's organization. Members restricted to some channel accounts only see those accounts' conversations.
- Unknown query parameters are rejected with `400 Bad Request`.

<a id="conversations--get"></a>

### Get a conversation

Source: https://www.achieveapex.com/docs/api-reference/conversations/get

Retrieve one conversation by ID.

#### Endpoint

`GET /conversations/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | integer | Yes | Conversation ID. |

#### Request

```bash
curl https://integrations.achieveapex.com/conversations/5001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 5001,
  "organization_id": 456,
  "channel": "whatsapp",
  "contact_id": 88001,
  "whatsapp_channel_id": 12,
  "status": "open",
  "unread_count": 0,
  "assigned_user_id": 12,
  "assigned_ai_assistant_id": 3,
  "pipeline_id": 10,
  "pipeline_stage_id": 55,
  "blocked": false,
  "ai_context_cut": null,
  "ai_auto_assignment_disabled": false,
  "ai_auto_assignment_disabled_reason": null,
  "meta_contact_first_name": "Maria",
  "meta_contact_last_name": "Lopez",
  "meta_contact_channel_wa_id": "573001234567",
  "last_interaction_at": "2026-02-10T15:22:00.000Z",
  "created_at": "2026-02-01T09:00:00.000Z",
  "updated_at": "2026-02-10T15:22:00.000Z",
  "deleted_at": null
}
```

The response is the full [conversation object](#conversations) (shortened here).

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The ID does not exist, was deleted, or belongs to an organization your API key cannot access. |

<a id="conversations--create"></a>

### Create a conversation

Source: https://www.achieveapex.com/docs/api-reference/conversations/create

Create a conversation record. Use it for **AI assistant playground** threads (test an assistant through the API). To write to a contact on WhatsApp use [Start a WhatsApp conversation](#conversations--initiate-whatsapp) instead: it picks the WhatsApp number and fills the channel identifiers for you.

#### Endpoint

`POST /conversations`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. |
| `contact_id` | integer | Yes | [Contact](#contacts) of the thread. |
| `channel` | string | Yes | `playground` for AI testing. Other values: `whatsapp`, `instagram`, `messenger`, `webchat`, `sms`. |
| `assigned_ai_assistant_id` | integer | No | AI assistant that answers the thread. Must belong to the organization. |
| `assigned_user_id` | integer | No | Human owner. Must be a member of the organization. |
| `meta_contact_first_name` | string | No | Contact first name shown in the inbox and used by search. |
| `meta_contact_last_name` | string | No | Contact last name. |
| `meta_contact_avatar_url` | string \| null | No | Contact avatar URL. |
| `pipeline_id` / `pipeline_stage_id` | integer | No | Place the thread in a conversation pipeline. |
| `status` | string | No | `open` (default) or `closed`. |

Any other writable [conversation field](#conversations) is accepted. `meta_contact_tags` is always copied from the contact.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "contact_id": 88001,
    "channel": "playground",
    "assigned_ai_assistant_id": 3,
    "meta_contact_first_name": "Test",
    "meta_contact_last_name": "User"
  }'
```

Then send a message as the contact with `POST /conversation-messages-playground` (see [Send a message](#conversation-messages--send)) and the assistant replies in the same thread.

#### Response

```json
{
  "id": 5100,
  "organization_id": 456,
  "channel": "playground",
  "contact_id": 88001,
  "assigned_ai_assistant_id": 3,
  "assigned_user_id": null,
  "status": "open",
  "unread_count": 0,
  "meta_contact_first_name": "Test",
  "meta_contact_last_name": "User",
  "meta_contact_tags": [],
  "pinned_messages": [],
  "created_at": "2026-02-10T15:00:00.000Z",
  "updated_at": "2026-02-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Behavior

- **Duplicates:** for SMS, when a conversation with the same `contact_phone` and `our_phone_number` already exists, that conversation is updated with the body and returned instead of creating a new one. The same applies to WhatsApp and Instagram when the channel identifiers match.
- Creating a conversation can start automations with a "conversation created" trigger.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | A required field is missing, `channel` is not one of the allowed values, or `assigned_user_id` / `assigned_ai_assistant_id` does not belong to the organization. |

<a id="conversations--patch"></a>

### Update a conversation

Source: https://www.achieveapex.com/docs/api-reference/conversations/patch

Partially update one conversation: open or close it, assign a human or an AI assistant, move it in a pipeline, mark it read or unread, cut the AI context, pin messages or block it. Send only the fields you want to change.

#### Endpoint

`PATCH /conversations/:id`

#### Body

Any writable [conversation field](#conversations). The common ones:

| Name | Type | Description |
|---|---|---|
| `status` | string | `open` or `closed`. |
| `assigned_user_id` | integer \| null | Human owner. Must be a member of the organization. `null` unassigns. |
| `assigned_ai_assistant_id` | integer \| null | AI assistant. Must belong to the organization. `null` unassigns. Assigning one also resets the AI safeguards (`token_limit_reached_at`, `token_limit_reason`) and sets `ai_auto_assignment_disabled` to `false`. |
| `pipeline_id` | integer \| null | Conversation pipeline. It must accept the conversation's channel ([channel scope](https://www.achieveapex.com/docs/api-reference/pipelines/overview#channel-scope-conversation-pipelines)). |
| `pipeline_stage_id` | integer \| null | Stage of `pipeline_id`. `null` puts the thread in the Incoming column. |
| `unread_count` | integer | `0` marks the thread read, `1` marks it unread. |
| `ai_context_cut` | string | Any non-empty value. The server sets it to the current time, clears `conversation_summary` and `handoff_reason`, and adds a "AI Context Cut" system message. The AI assistant then ignores older messages. |
| `ai_auto_assignment_disabled` | boolean | `true` makes automatic AI assignment rules skip the thread. |
| `ai_auto_assignment_disabled_reason` | string \| null | Reason stored with the flag. |
| `blocked` | boolean | `true` ignores new incoming messages of the thread. |
| `pinned_messages` | array | Full list of pinned messages (max 3). Each item: `message_id` (required), `message_type`, `preview` (required, max 2000 chars), `destination`, `pinned_at`, `pinned_by_user_id`. System, tool, reaction and error messages cannot be pinned. |
| `next_follow_up_date_time` | string (date-time) | Schedules the next AI follow-up at that time. |

`organization_id` and server-managed fields (`last_message_*`, counters, summaries) should not be sent.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/conversations/5001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed",
    "assigned_user_id": 12
  }'
```

Move to a pipeline stage:

```bash
curl -X PATCH https://integrations.achieveapex.com/conversations/5001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_id": 10, "pipeline_stage_id": 55 }'
```

Assign an AI assistant and cut its context so it starts fresh:

```bash
curl -X PATCH https://integrations.achieveapex.com/conversations/5001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_ai_assistant_id": 3, "ai_context_cut": "now" }'
```

#### Response

The updated [conversation object](#conversations).

```json
{
  "id": 5001,
  "organization_id": 456,
  "channel": "whatsapp",
  "status": "closed",
  "assigned_user_id": 12,
  "assigned_ai_assistant_id": 3,
  "pipeline_id": 10,
  "pipeline_stage_id": 55,
  "updated_at": "2026-02-10T16:00:00.000Z"
}
```

#### Side effects

- Changing `assigned_user_id` notifies the new owner.
- Pipeline and stage changes are recorded in the conversation's stage history.
- Updates can start automations with a "conversation updated" trigger (for example a stage change).

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | The user or AI assistant does not belong to the organization, the pipeline is not accessible, the pipeline does not accept the conversation's channel (`data.code = "PIPELINE_CHANNEL_NOT_ALLOWED"`), or `pinned_messages` is invalid (more than 3, missing text, or a message type that cannot be pinned). |
| `404 Not Found` | The conversation does not exist or was deleted. |

<a id="conversations--delete"></a>

### Delete a conversation

Source: https://www.achieveapex.com/docs/api-reference/conversations/delete

Delete a conversation. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get responses. Its messages are kept.

#### Endpoint

`DELETE /conversations/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | integer | Yes | Conversation ID. |

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/conversations/5001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [conversation object](#conversations), with `deleted_at` set.

```json
{
  "id": 5001,
  "organization_id": 456,
  "channel": "whatsapp",
  "status": "open",
  "deleted_at": "2026-02-10T16:30:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | Your API key's role is not allowed to delete conversations. |
| `404 Not Found` | The conversation does not exist or was already deleted. |

<a id="conversations--bulk-actions-get"></a>

### Get a bulk action

Source: https://www.achieveapex.com/docs/api-reference/conversations/bulk-actions-get

Retrieve one conversation bulk action by ID, for example to read its `processed_count` and `error_message`.

#### Endpoint

`GET /conversations-bulk-actions/:id`

#### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | integer | Yes | Bulk action ID. |

#### Request

```bash
curl https://integrations.achieveapex.com/conversations-bulk-actions/310 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 310,
  "organization_id": 456,
  "created_by_user_id": 12,
  "action": "assign",
  "action_params": { "user_id": 12 },
  "conversation_ids": [5001, 5002, 5003],
  "view_id": null,
  "filter": null,
  "status": "completed",
  "processed_count": 3,
  "failed_count": 0,
  "error_message": null,
  "created_at": "2026-02-10T16:00:00.000Z",
  "updated_at": "2026-02-10T16:00:00.000Z",
  "deleted_at": null
}
```

Fields are described in [The bulk action object](#conversations--bulk-actions-list). Only owners and admins of the organization can read bulk actions.

<a id="conversations--bulk-actions-list"></a>

### List bulk actions

Source: https://www.achieveapex.com/docs/api-reference/conversations/bulk-actions-list

List the conversation bulk actions run in your organization, newest first if you sort by `created_at`. Useful as an audit log of mass changes.

#### Endpoint

`GET /conversations-bulk-actions`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization. Results are always limited to organizations where your API key's user is owner or admin. |
| `action` | string | No | `assign`, `update_status`, `assign_ai_assistant`, `move` or `cut_ai_context`. |
| `status` | string | No | `pending`, `processing`, `completed` or `failed`. |
| `created_by_user_id` | integer | No | User who ran the action. |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[created_at]` | `1` \| `-1` | No | Sort order. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/conversations-bulk-actions \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'status=failed' \
  --data-urlencode '$sort[created_at]=-1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 311,
      "organization_id": 456,
      "created_by_user_id": 12,
      "action": "move",
      "action_params": { "pipeline_id": 99 },
      "conversation_ids": [5001],
      "view_id": null,
      "filter": null,
      "status": "failed",
      "processed_count": 0,
      "failed_count": 1,
      "error_message": "Selected pipeline was not found",
      "created_at": "2026-02-10T16:05:00.000Z",
      "updated_at": "2026-02-10T16:05:00.000Z",
      "deleted_at": null
    }
  ]
}
```

#### The bulk action object

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization the action ran in. |
| `created_by_user_id` | integer | Read-only. User who ran it (the API key's user). |
| `action` | string | `assign`, `update_status`, `assign_ai_assistant`, `move` or `cut_ai_context`. |
| `action_params` | object \| null | Parameters sent with the action. |
| `conversation_ids` | integer[] \| null | Conversations targeted (resolved from `filter` when one was used). |
| `view_id` | integer \| null | Saved view ID. Not resolved by the server; always send `conversation_ids` or `filter`. |
| `filter` | object \| null | Filter used to pick the conversations: `organization_id`, `pipeline_id`, `pipeline_stage_id`, `status`, `channel`, `assigned_user_id`, `assigned_ai_assistant_id`. |
| `status` | string | Read-only. `pending`, `processing`, `completed` or `failed`. |
| `processed_count` | integer | Read-only. Conversations changed. |
| `failed_count` | integer | Read-only. Conversations that could not be changed. |
| `error_message` | string \| null | Read-only. Error when the action failed. |
| `created_at` | string (date-time) | Read-only. |
| `updated_at` | string (date-time) | Read-only. |
| `deleted_at` | string (date-time) \| null | Read-only. |

<a id="conversations--bulk-actions"></a>

### Run a bulk action on conversations

Source: https://www.achieveapex.com/docs/api-reference/conversations/bulk-actions

Apply the same change to many conversations in one request: assign an owner, change status, assign an AI assistant, move them in a pipeline, or cut the AI context. The action runs during the request and the response is the bulk action record with its result counts.

Bulk actions write directly to the database: they **do not trigger automations**, webhooks or realtime events that the same change would fire when made on a single conversation.

#### Endpoint

`POST /conversations-bulk-actions`

The API key must belong to an **owner or admin** of the organization.

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. Only conversations of this organization are changed. |
| `action` | string | Yes | One of `assign`, `update_status`, `assign_ai_assistant`, `move`, `cut_ai_context`. |
| `action_params` | object | Yes | Parameters of the action (table below). |
| `conversation_ids` | integer[] | One of | Conversations to change. |
| `filter` | object | One of | Instead of IDs, change every conversation matching the filter. Needs at least one of `pipeline_id`, `pipeline_stage_id` (`null` = Incoming column), `status` (`open`/`closed`), `channel`, `assigned_user_id`, `assigned_ai_assistant_id`. |

Send `conversation_ids` or `filter`. The schema also has a `view_id` field, but saved views are not resolved: a request with only `view_id` is rejected.

##### `action_params` per action

| `action` | `action_params` | Effect |
|---|---|---|
| `assign` | `{ "user_id": 12 }` or `{ "user_id": null }` | Sets or clears the human owner. |
| `update_status` | `{ "status": "open" }` or `{ "status": "closed" }` | Opens or closes the conversations. |
| `assign_ai_assistant` | `{ "ai_assistant_id": 3 }` or `{ "ai_assistant_id": null }` | Sets or clears the AI assistant. |
| `move` | `{ "pipeline_id": 10, "pipeline_stage_id": 55 }` | Moves to a conversation pipeline. `pipeline_stage_id` `null` or omitted = the pipeline's Incoming column. The stage must belong to the pipeline. |
| `cut_ai_context` | `{}` | Sets `ai_context_cut` to now, so the AI assistant ignores every earlier message, and clears `conversation_summary` and `handoff_reason`. Adds a "✂️ AI Context Cut" system message to each conversation. No message is deleted. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversations-bulk-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "assign",
    "action_params": { "user_id": 12 },
    "conversation_ids": [5001, 5002, 5003]
  }'
```

Close every open WhatsApp conversation of one stage:

```bash
curl -X POST https://integrations.achieveapex.com/conversations-bulk-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "update_status",
    "action_params": { "status": "closed" },
    "filter": {
      "pipeline_id": 10,
      "pipeline_stage_id": 55,
      "status": "open",
      "channel": "whatsapp"
    }
  }'
```

#### Response

The [bulk action record](#conversations--bulk-actions-list). With a `filter`, `conversation_ids` contains the IDs it resolved to.

```json
{
  "id": 310,
  "organization_id": 456,
  "created_by_user_id": 12,
  "action": "assign",
  "action_params": { "user_id": 12 },
  "conversation_ids": [5001, 5002, 5003],
  "view_id": null,
  "filter": null,
  "status": "completed",
  "processed_count": 3,
  "failed_count": 0,
  "error_message": null,
  "created_at": "2026-02-10T16:00:00.000Z",
  "updated_at": "2026-02-10T16:00:00.000Z",
  "deleted_at": null
}
```

`status` is `failed` (with `error_message`) when the action could not run, for example a missing `action_params` value or a pipeline that does not exist. Bulk changes do not send assignment notifications or start automations.

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The API key's user is not an owner or admin of `organization_id`. |
| `400` / `500` | Neither `conversation_ids` nor a usable `filter` was sent, the filter has no restrictive field, or it matches no conversation. |

<a id="conversations--initiate-whatsapp"></a>

### Start a WhatsApp conversation

Source: https://www.achieveapex.com/docs/api-reference/conversations/initiate-whatsapp

Start (or reuse) the WhatsApp conversation with a contact from one of your WhatsApp numbers. An organization can connect several numbers: each number has its own conversation with the contact, and messages always go out from the conversation's number.

#### Endpoint

`POST /conversation-initiate-whatsapp`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. |
| `contact_id` | integer | Yes | Contact to write to. Needs a WhatsApp ID, a phone with country code (`phone` + `phone_country_code`), or a WhatsApp Business-Scoped User ID. |
| `whatsapp_channel_id` | integer | No | Number to write from: an `id` from [List WhatsApp numbers](#whatsapp-channels--list). Must be an active number of the organization. |
| `whatsapp_number` | string | No | Alternative to `whatsapp_channel_id`: the number's ID, internal name (`label`, e.g. `"Ventas"`), verified name, or phone number (at least 6 digits, any format). |

**Which number is used:** `whatsapp_channel_id`, else `whatsapp_number`, else the **oldest active number** of the organization (lowest `id`).

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversation-initiate-whatsapp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "contact_id": 7890,
    "whatsapp_channel_id": 12
  }'
```

#### Response

The [conversation object](#conversations). If the contact already has a conversation on that number it is returned instead of creating a new one.

```json
{
  "id": 5200,
  "organization_id": 456,
  "channel": "whatsapp",
  "contact_id": 7890,
  "whatsapp_channel_id": 12,
  "status": "open",
  "assigned_user_id": 12,
  "meta_contact_first_name": "Ana",
  "meta_contact_last_name": "Gomez",
  "meta_contact_channel_wa_id": "573001112233",
  "unread_count": 0,
  "created_at": "2026-02-10T17:00:00.000Z"
}
```

#### Behavior

- A new conversation is assigned to the API key's user (`assigned_user_id`).
- When the contact has a phone but no WhatsApp ID, the contact's `channel_whatsapp_wa_id` is filled from `phone_country_code` + `phone`.
- Then send a [WhatsApp template](#conversation-messages--send-whatsapp-template) (required to open a chat outside the 24-hour window) or a [regular message](#conversation-messages--send).
- Members restricted to some numbers (channel access rules) cannot start conversations from numbers they cannot see.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `organization_id` or `contact_id` missing; the number is not an active number of the organization; no number matches `whatsapp_number`; the organization has no active WhatsApp number; the contact has no phone or WhatsApp ID. |
| `403 Forbidden` | The API key's user has no access to that WhatsApp number. |

---

## Custom fields

<a id="custom-fields"></a>

### Custom fields overview

Source: https://www.achieveapex.com/docs/api-reference/custom-fields

Custom fields are the extra properties your organization defines for contacts, companies, deals, tickets, reservations, sales documents and products. Each field has a `key`; you write values on a record with `custom_fields_by_key` using that key.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/custom-fields` | [List custom fields](#custom-fields--list) |
| `GET` | `/custom-fields/:id` | [Get a custom field](#custom-fields--get) |
| `POST` | `/custom-fields` | [Create a custom field](#custom-fields--create) |
| `PATCH` | `/custom-fields/:id` | [Update a custom field](#custom-fields--update) |
| `DELETE` | `/custom-fields/:id` | [Delete a custom field](#custom-fields--delete) |

Reads are limited to your API key's organization. Pass `organization_id` and `entity_type` as filters to get the fields of one record type.

#### The custom field object

```json
{
  "id": 12,
  "organization_id": 456,
  "entity_type": "contact",
  "name": "Membership level",
  "key": "membership_level",
  "fieldType": "select",
  "isRequired": false,
  "options": [
    { "value": "Silver", "order": 0 },
    { "value": "Gold", "order": 1 }
  ],
  "system_currency_id": null,
  "custom_field_category_id": null,
  "position": 3,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

A `currency` field also returns a `currency` object with the formatting of its currency:

```json
{
  "id": 14,
  "name": "Budget",
  "key": "budget",
  "fieldType": "currency",
  "system_currency_id": 2,
  "currency": {
    "id": 2,
    "currency_code": "USD",
    "currency_name": "US Dollar",
    "currency_symbol": "$",
    "decimal_places": 2,
    "thousand_separator": ",",
    "decimal_separator": ".",
    "currency_format": "{symbol}{amount}"
  }
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the field. Required on create. |
| `entity_type` | string | Record type the field belongs to: `contact`, `company`, `deal`, `ticket`, `reservation`, `sales_document` or `product`. Required on create. |
| `name` | string | Display name. Required on create. Must be unique (case-insensitive) among the organization's active fields of the same `entity_type`. |
| `key` | string | Identifier used in `custom_fields_by_key`. Generated from `name` on create (lowercase, spaces to `_`, e.g. `Membership level` → `membership_level`) with a numeric suffix if taken. You may send your own `key` on create; it cannot be changed afterwards. |
| `fieldType` | string | One of `text`, `textarea`, `number`, `date`, `time`, `datetime`, `boolean`, `select`, `multiselect`, `email`, `url`, `phone`, `file`, `multifile`, `image`, `currency`, `json`. Required on create. |
| `isRequired` | boolean | Whether the app requires a value. Required on create. |
| `options` | array | Choices for `select` and `multiselect`, as `{ "value": string, "order": integer }`. |
| `system_currency_id` | integer \| null | Currency of a `currency` field. Required for `currency` fields and must be a currency enabled in the organization. Cleared for other types. |
| `custom_field_category_id` | integer \| null | Category (group) the field is shown under in the app. |
| `position` | integer | Sort order within the entity type. Defaults to the end of the list. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the field is deleted. |

#### Value formats

When writing `custom_fields_by_key` on a record, each value is validated against the field type: `number` and `currency` must be numbers, `boolean` true/false, `date`/`time`/`datetime` valid date or time strings, `email` a valid email, `url` a URL starting with `http://` or `https://`, `phone` at least 7 digits, `select` one of the `options` values (case-insensitive) and `multiselect` an array of them.

#### Related

- [Contacts](#contacts)
- [Companies](#companies)
- [Deals](#deals)
- [Products](#products)

<a id="custom-fields--list"></a>

### List custom fields

Source: https://www.achieveapex.com/docs/api-reference/custom-fields/list

Returns the custom fields of your organization, sorted by `position` by default.

#### Endpoint

`GET /custom-fields`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only fields of this organization. |
| `entity_type` | string | No | `contact`, `company`, `deal`, `ticket`, `reservation`, `sales_document` or `product`. |
| any custom field attribute | mixed | No | Filter with Feathers syntax, e.g. `fieldType=select`, `key[$in][]=industry`. |
| `fastJoinForCustomFieldsList` | string | No | Set to `true` to embed the `category` object (`id`, `name`, `organization_id`, `display_order`). |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Default `position` then `id` ascending. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/custom-fields \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'entity_type=contact' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 12,
      "organization_id": 456,
      "entity_type": "contact",
      "name": "Membership level",
      "key": "membership_level",
      "fieldType": "select",
      "isRequired": false,
      "options": [
        { "value": "Silver", "order": 0 },
        { "value": "Gold", "order": 1 }
      ],
      "system_currency_id": null,
      "custom_field_category_id": null,
      "position": 3,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="custom-fields--get"></a>

### Get a custom field

Source: https://www.achieveapex.com/docs/api-reference/custom-fields/get

Returns one custom field by ID.

#### Endpoint

`GET /custom-fields/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/custom-fields/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [custom field object](#custom-fields).

```json
{
  "id": 12,
  "organization_id": 456,
  "entity_type": "contact",
  "name": "Membership level",
  "key": "membership_level",
  "fieldType": "select",
  "isRequired": false,
  "options": [
    { "value": "Silver", "order": 0 },
    { "value": "Gold", "order": 1 }
  ],
  "system_currency_id": null,
  "custom_field_category_id": null,
  "position": 3,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

<a id="custom-fields--create"></a>

### Create a custom field

Source: https://www.achieveapex.com/docs/api-reference/custom-fields/create

Creates a custom field for one entity type.

#### Endpoint

`POST /custom-fields`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the field in. |
| `entity_type` | string | Yes | `contact`, `company`, `deal`, `ticket`, `reservation`, `sales_document` or `product`. |
| `name` | string | Yes | Display name. Unique among active fields of the same entity type. |
| `fieldType` | string | Yes | See the [field types](#custom-fields). |
| `isRequired` | boolean | Yes | Whether the app requires a value. |
| `options` | array | For `select` / `multiselect` | `{ "value": string, "order": integer }` items. |
| `system_currency_id` | integer | For `currency` | A currency enabled in the organization. |
| `key` | string | No | Custom key. Defaults to a slug of `name`; a numeric suffix is added if the key is taken. |
| `custom_field_category_id` | integer | No | Category to show the field under. |
| `position` | integer | No | Sort order. Defaults to the end of the list for this entity type. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/custom-fields \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "entity_type": "contact",
    "name": "Membership level",
    "fieldType": "select",
    "isRequired": false,
    "options": [
      { "value": "Silver", "order": 0 },
      { "value": "Gold", "order": 1 }
    ]
  }'
```

#### Response

```json
{
  "id": 12,
  "organization_id": 456,
  "entity_type": "contact",
  "name": "Membership level",
  "key": "membership_level",
  "fieldType": "select",
  "isRequired": false,
  "options": [
    { "value": "Silver", "order": 0 },
    { "value": "Gold", "order": 1 }
  ],
  "system_currency_id": null,
  "custom_field_category_id": null,
  "position": 3,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | A field with the same name already exists for this entity type, a required attribute is missing, a `currency` field has no valid `system_currency_id`, or the currency is not enabled in the organization. |

<a id="custom-fields--update"></a>

### Update a custom field

Source: https://www.achieveapex.com/docs/api-reference/custom-fields/update

Partially updates a custom field. `key` cannot be changed (it is ignored), so values already stored on records keep working.

#### Endpoint

`PATCH /custom-fields/:id`

#### Body

Any writable attribute of the [custom field object](#custom-fields): `name`, `fieldType`, `isRequired`, `options`, `system_currency_id`, `custom_field_category_id`, `position`. A new `name` must still be unique for the entity type.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/custom-fields/12 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": [
      { "value": "Silver", "order": 0 },
      { "value": "Gold", "order": 1 },
      { "value": "Platinum", "order": 2 }
    ]
  }'
```

#### Response

Returns the updated [custom field object](#custom-fields).

```json
{
  "id": 12,
  "organization_id": 456,
  "entity_type": "contact",
  "name": "Membership level",
  "key": "membership_level",
  "fieldType": "select",
  "isRequired": false,
  "options": [
    { "value": "Silver", "order": 0 },
    { "value": "Gold", "order": 1 },
    { "value": "Platinum", "order": 2 }
  ],
  "position": 3,
  "updated_at": "2026-01-05T00:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | The new name is already used for this entity type, or the currency rules for `currency` fields are not met. |

<a id="custom-fields--delete"></a>

### Delete a custom field

Source: https://www.achieveapex.com/docs/api-reference/custom-fields/delete

Deletes a custom field. This is a soft delete: the field gets a `deleted_at` timestamp and no longer appears in list or get. Its key stays reserved, so a new field with the same name gets a different key.

#### Endpoint

`DELETE /custom-fields/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/custom-fields/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [custom field object](#custom-fields) with `deleted_at` set.

```json
{
  "id": 12,
  "organization_id": 456,
  "entity_type": "contact",
  "name": "Membership level",
  "key": "membership_level",
  "deleted_at": "2026-01-06T00:00:00.000Z"
}
```

---

## Deal products

<a id="deal-products"></a>

### Deal products overview

Source: https://www.achieveapex.com/docs/api-reference/deal-products

A deal product is a line item on a [deal](#deals): a product (or free-text item) with quantity, unit price, discount and tax. The deal's `amount` is kept equal to the sum of `total_amount_with_tax` of its deal products.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/deal-products` | [List deal products](#deal-products--list) |
| `GET` | `/deal-products/:id` | [Get a deal product](#deal-products--get) |
| `POST` | `/deal-products` | [Add a product to a deal](#deal-products--create) |
| `PATCH` | `/deal-products/:id` | [Update a deal product](#deal-products--update) |
| `DELETE` | `/deal-products/:id` | [Remove a product from a deal](#deal-products--delete) |

Reads are limited to your API key's organization. Filter by `deal_id` to get the line items of one deal.

#### The deal product object

```json
{
  "id": 501,
  "organization_id": 456,
  "deal_id": 55,
  "product_id": 601,
  "name": "Annual license",
  "sku": "LIC-001",
  "description": "Enterprise tier",
  "main_media_path": "organizations/456/products/601/cover.jpg",
  "quantity": "2.00",
  "price": "10000.00",
  "discount_type": "percentage",
  "discount_amount": "0.00",
  "discount_percentage": "10.00",
  "tax_percentage": "7.00",
  "total_amount_without_tax": "18000.00",
  "total_amount_with_tax": "19260.00",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null
}
```

Numeric amounts are decimal columns and are returned as strings.

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the line. Required on create. |
| `deal_id` | integer | Deal the line belongs to. Required on create. |
| `product_id` | integer | [Product](#products) from the catalog, if the line comes from one. |
| `name` | string \| null | Item name shown on the deal. |
| `sku` | string \| null | Item SKU. |
| `description` | string \| null | Item description. |
| `main_media_path` | string \| null | Image of the item (storage path or URL), usually the product's main image. |
| `quantity` | number | Quantity. Default `0`. |
| `price` | number | Unit price. Default `0`. |
| `discount_type` | string | `fixed`, `percentage` or `none`. Default `none`. |
| `discount_amount` | number | Discount amount for `fixed`. Default `0`. |
| `discount_percentage` | number | Discount percentage for `percentage`. Default `0`. |
| `tax_percentage` | number | Tax percentage. Default `0`. |
| `total_amount_without_tax` | number | Line total before tax. Required on create. Not calculated by the API: send the value you want stored. |
| `total_amount_with_tax` | number | Line total including tax. Required on create. Not calculated by the API; this is the value added to the deal `amount`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the line is removed. |

#### Related

- [Deals](#deals)
- [Products](#products)
- [Errors](#deal-products--errors)

<a id="deal-products--list"></a>

### List deal products

Source: https://www.achieveapex.com/docs/api-reference/deal-products/list

Returns a paginated list of deal product lines.

#### Endpoint

`GET /deal-products`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `deal_id` | integer | No | Only lines of this deal. |
| `organization_id` | integer | No | Only lines of this organization. |
| any deal product field | mixed | No | Filter with Feathers syntax, e.g. `product_id=601`, `deal_id[$in][]=55`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[created_at]=1`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/deal-products \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'deal_id=55' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 501,
      "organization_id": 456,
      "deal_id": 55,
      "product_id": 601,
      "name": "Annual license",
      "sku": "LIC-001",
      "quantity": "2.00",
      "price": "10000.00",
      "discount_type": "percentage",
      "discount_amount": "0.00",
      "discount_percentage": "10.00",
      "tax_percentage": "7.00",
      "total_amount_without_tax": "18000.00",
      "total_amount_with_tax": "19260.00",
      "deleted_at": null
    }
  ]
}
```

<a id="deal-products--get"></a>

### Get a deal product

Source: https://www.achieveapex.com/docs/api-reference/deal-products/get

Returns one deal product line by ID.

#### Endpoint

`GET /deal-products/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/deal-products/501 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [deal product object](#deal-products).

```json
{
  "id": 501,
  "organization_id": 456,
  "deal_id": 55,
  "product_id": 601,
  "name": "Annual license",
  "sku": "LIC-001",
  "description": "Enterprise tier",
  "main_media_path": null,
  "quantity": "2.00",
  "price": "10000.00",
  "discount_type": "percentage",
  "discount_amount": "0.00",
  "discount_percentage": "10.00",
  "tax_percentage": "7.00",
  "total_amount_without_tax": "18000.00",
  "total_amount_with_tax": "19260.00",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null
}
```

<a id="deal-products--create"></a>

### Add a product to a deal

Source: https://www.achieveapex.com/docs/api-reference/deal-products/create

Creates a line item on a deal. Afterwards the deal's `amount` is recalculated as the sum of `total_amount_with_tax` of all its lines.

#### Endpoint

`POST /deal-products`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization of the deal. |
| `deal_id` | integer | Yes | Deal to add the line to. |
| `total_amount_without_tax` | number | Yes | Line total before tax. Not calculated by the API. |
| `total_amount_with_tax` | number | Yes | Line total including tax. Not calculated by the API. |
| `product_id` | integer | No | Catalog product. |
| `name` | string | No | Item name. |
| `sku` | string | No | Item SKU. |
| `description` | string | No | Item description. |
| `main_media_path` | string | No | Item image. |
| `quantity` | number | No | Default `0`. |
| `price` | number | No | Unit price. Default `0`. |
| `discount_type` | string | No | `fixed`, `percentage` or `none`. Default `none`. |
| `discount_amount` | number | No | For `fixed`. |
| `discount_percentage` | number | No | For `percentage`. |
| `tax_percentage` | number | No | Default `0`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/deal-products \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "deal_id": 55,
    "product_id": 601,
    "name": "Annual license",
    "sku": "LIC-001",
    "quantity": 2,
    "price": 10000,
    "discount_type": "percentage",
    "discount_percentage": 10,
    "tax_percentage": 7,
    "total_amount_without_tax": 18000,
    "total_amount_with_tax": 19260
  }'
```

#### Response

```json
{
  "id": 501,
  "organization_id": 456,
  "deal_id": 55,
  "product_id": 601,
  "name": "Annual license",
  "sku": "LIC-001",
  "description": null,
  "main_media_path": null,
  "quantity": "2.00",
  "price": "10000.00",
  "discount_type": "percentage",
  "discount_amount": "0.00",
  "discount_percentage": "10.00",
  "tax_percentage": "7.00",
  "total_amount_without_tax": "18000.00",
  "total_amount_with_tax": "19260.00",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null
}
```

<a id="deal-products--update"></a>

### Update a deal product

Source: https://www.achieveapex.com/docs/api-reference/deal-products/update

Partially updates a deal product line. The deal's `amount` is recalculated afterwards. If you change quantity, price, discount or tax, also send the new `total_amount_without_tax` and `total_amount_with_tax`: the API does not recalculate them.

#### Endpoint

`PATCH /deal-products/:id`

#### Body

Any writable field of the [deal product object](#deal-products). Fields not in the object are rejected.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/deal-products/501 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "total_amount_without_tax": 27000,
    "total_amount_with_tax": 28890
  }'
```

#### Response

Returns the updated [deal product object](#deal-products).

```json
{
  "id": 501,
  "deal_id": 55,
  "quantity": "3.00",
  "price": "10000.00",
  "total_amount_without_tax": "27000.00",
  "total_amount_with_tax": "28890.00",
  "updated_at": "2026-04-02T10:00:00.000Z",
  "deleted_at": null
}
```

<a id="deal-products--delete"></a>

### Remove a product from a deal

Source: https://www.achieveapex.com/docs/api-reference/deal-products/delete

Deletes a deal product line. This is a soft delete: the line gets a `deleted_at` timestamp and no longer appears in list or get. The deal's `amount` is recalculated without it.

#### Endpoint

`DELETE /deal-products/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/deal-products/501 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [deal product object](#deal-products) with `deleted_at` set.

```json
{
  "id": 501,
  "deal_id": 55,
  "name": "Annual license",
  "deleted_at": "2026-04-03T08:00:00.000Z"
}
```

<a id="deal-products--errors"></a>

### Deal products errors

Source: https://www.achieveapex.com/docs/api-reference/deal-products/errors

Errors use the standard Feathers error format.

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query, e.g. an unknown field or an invalid `discount_type`. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, or the record belongs to an organization the key cannot access. |
| `404 Not Found` | The deal product does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error, e.g. a missing `deal_id` or missing totals on create (required by the database). |

---

## Deals

<a id="deals"></a>

### Deals overview

Source: https://www.achieveapex.com/docs/api-reference/deals

A deal is a sales opportunity that moves through the stages of a deal [pipeline](#pipelines). Each deal belongs to a contact, can be linked to a company, has an amount in a currency, and is `open`, `won` or `lost`.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/deals` | [List deals](#deals--list) |
| `GET` | `/deals/:id` | [Get a deal](#deals--get) |
| `POST` | `/deals` | [Create a deal](#deals--create) |
| `PATCH` | `/deals/:id` | [Update a deal](#deals--update) |
| `DELETE` | `/deals/:id` | [Delete a deal](#deals--delete) |

Reads are limited to your API key's organization. Pass `organization_id` as a filter to work with one organization. Creating a deal in, or moving it to, a private pipeline requires the key's user to have access to that pipeline.

#### The deal object

```json
{
  "id": 55,
  "name": "Annual plan",
  "amount": "12000.00",
  "currency_id": 2,
  "exchange_rate": "1.000000",
  "currency_symbol": "$",
  "currency_format": "{symbol}{amount}",
  "decimal_places": 2,
  "thousand_separator": ",",
  "decimal_separator": ".",
  "status": "open",
  "expected_close_date": "2026-06-30T00:00:00.000Z",
  "won_date": null,
  "lost_date": null,
  "deal_lost_reason_id": null,
  "deal_lost_reason": null,
  "organization_id": 456,
  "pipeline_id": 10,
  "pipeline_stage_id": 101,
  "contact_id": 123,
  "company_id": 101,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "custom_fields_by_key": { "source": "Website" },
  "custom_fields_by_name": { "Source": "Website" },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 40,
      "custom_field_key": "source",
      "custom_field_name": "Source",
      "custom_field_value": "Website"
    }
  ],
  "tags": [{ "id": 3, "name": "Hot", "color": "#EF4444" }],
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null
}
```

`amount` and `exchange_rate` are decimal columns and are returned as strings.

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Deal name. Required on create. |
| `amount` | number | Deal value. Default `0`. Recalculated automatically as the sum of `total_amount_with_tax` of the deal's [deal products](#deal-products) whenever one is added, changed or removed. |
| `currency_id` | integer | Currency of the deal (a system currency ID). |
| `exchange_rate` | number \| null | Rate from the deal currency to the organization's base currency. Calculated when `currency_id` is set or changed, unless you send it. `1` when the currency is the base currency. |
| `currency_symbol` | string \| null | Display symbol, copied from the currency when `currency_id` is set. |
| `currency_format` | string \| null | Display format, e.g. `{symbol}{amount}`. Copied from the currency. |
| `decimal_places` | number \| null | Display decimals. Default `2`. Copied from the currency. |
| `thousand_separator` | string \| null | Display thousands separator. Default `,`. |
| `decimal_separator` | string \| null | Display decimal separator. Default `.`. |
| `status` | string | `open`, `won` or `lost`. |
| `expected_close_date` | string (date-time) \| null | Expected close date. |
| `won_date` | string (date-time) \| null | Read-only. Set to now when `status` changes to `won`; cleared otherwise. |
| `lost_date` | string (date-time) \| null | Read-only. Set to now when `status` changes to `lost`; cleared otherwise. |
| `deal_lost_reason_id` | integer \| null | Lost reason from the organization's list of lost reasons. Cleared when `status` goes back to `open`. |
| `deal_lost_reason` | string \| null | Lost reason text. Filled from `deal_lost_reason_id` when you send it. |
| `organization_id` | integer | Organization that owns the deal. Required on create. |
| `pipeline_id` | integer | Deal [pipeline](#pipelines) (`type: deal`). Required on create. |
| `pipeline_stage_id` | integer | Current [stage](#pipeline-stages) of the pipeline. Required on create. |
| `contact_id` | integer \| null | [Contact](#contacts) of the deal. Required on create. |
| `company_id` | integer \| null | Linked [company](#companies). |
| `created_by_user_id` | integer \| null | Read-only. User who created the deal (the API key's user). |
| `owned_by_user_id` | integer \| null | User who owns the deal. |
| `custom_fields_by_key` | object | Custom field values keyed by the field `key` (see [Custom fields](#custom-fields), `entity_type=deal`). This is the field you write. |
| `custom_fields_by_name` | object | Read-only. Same values keyed by the field name. |
| `custom_fields_meta_data` | array | Read-only. One entry per value: `custom_field_id`, `custom_field_key`, `custom_field_name`, `custom_field_value`. |
| `tags` | array | Deal tags as `{ id, name, color }`. Only `id` matters on write: tags are matched against the organization's deal tags and unknown IDs are dropped. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the deal is deleted. |

#### Embedded data

Pass `fastJoinForDealsList=true` on list or get (update responses always include it) to embed: `company`, `contact`, `owner`, `createdBy`, `pipeline`, `pipelineStage`, `currency`, `dealProducts`, `stageHistory`, `conversation` (the contact's most recent conversation), `activities` (pending activities) and `watchers`. `includeDealActivities=false` and `includeDealWatchers=false` leave out `activities` and `watchers`; `includeDealActivitySummary=true` adds `activitySummary`.

#### Related

- [Deal products](#deal-products)
- [Pipelines](#pipelines)
- [Pipeline stages](#pipeline-stages)
- [Activities](#activities)
- [Contacts](#contacts)
- [Companies](#companies)
- [Errors](#deals--errors)

<a id="deals--list"></a>

### List deals

Source: https://www.achieveapex.com/docs/api-reference/deals/list

Returns a paginated list of deals, with optional filters.

#### Endpoint

`GET /deals`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only deals of this organization. |
| any deal field | mixed | No | Filter with Feathers syntax, e.g. `status=open`, `pipeline_id=10`, `pipeline_stage_id[$in][]=101`, `contact_id=123`, `expected_close_date[$lte]=2026-06-30`. |
| `view_id` | integer | No | Apply the filters of a saved deals view. |
| `fastJoinForDealsList` | string | No | Set to `true` to embed related data (see [embedded data](#deals)). |
| `includeDealActivities` | string | No | With `fastJoinForDealsList`: `false` to leave out pending `activities`. Default `true`. |
| `includeDealActivitySummary` | string | No | With `fastJoinForDealsList`: `true` to add `activitySummary`. Default `false`. |
| `includeDealWatchers` | string | No | With `fastJoinForDealsList`: `false` to leave out `watchers`. Default `true`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[created_at]=-1`. |
| `$select[]` | string | No | Only return these fields. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/deals \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'pipeline_id=10' \
  --data-urlencode 'status=open' \
  --data-urlencode 'fastJoinForDealsList=true' \
  --data-urlencode 'includeDealWatchers=false' \
  --data-urlencode '$sort[created_at]=-1' \
  --data-urlencode '$limit=25'
```

#### Response

```json
{
  "total": 1,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 55,
      "name": "Annual plan",
      "amount": "12000.00",
      "currency_id": 2,
      "status": "open",
      "organization_id": 456,
      "pipeline_id": 10,
      "pipeline_stage_id": 101,
      "contact_id": 123,
      "company_id": 101,
      "owned_by_user_id": 789,
      "deleted_at": null,
      "pipeline": { "id": 10, "name": "Sales" },
      "pipelineStage": { "id": 101, "name": "Qualified", "pipeline_id": 10, "rotting_days": 14 },
      "contact": { "id": 123, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" },
      "company": { "id": 101, "name": "Acme Corporation" },
      "owner": { "id": 789, "first_name": "Ana", "last_name": "Lopez", "email": "ana@example.com" },
      "currency": { "id": 2, "currency_code": "USD", "currency_symbol": "$" },
      "dealProducts": [{ "id": 501, "deal_id": 55, "name": "Annual license", "quantity": "1.00", "price": "12000.00" }],
      "activities": []
    }
  ]
}
```

Each item is a full [deal object](#deals); it is shortened here.

<a id="deals--get"></a>

### Get a deal

Source: https://www.achieveapex.com/docs/api-reference/deals/get

Returns one deal by ID.

#### Endpoint

`GET /deals/:id`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `fastJoinForDealsList` | string | No | Set to `true` to embed related data (see [embedded data](#deals)). |
| `includeDealActivities` | string | No | `false` to leave out pending `activities`. |
| `includeDealActivitySummary` | string | No | `true` to add `activitySummary`. |
| `includeDealWatchers` | string | No | `false` to leave out `watchers`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/deals/55 \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'fastJoinForDealsList=true'
```

#### Response

Returns the [deal object](#deals).

```json
{
  "id": 55,
  "name": "Annual plan",
  "amount": "12000.00",
  "currency_id": 2,
  "status": "open",
  "organization_id": 456,
  "pipeline_id": 10,
  "pipeline_stage_id": 101,
  "contact_id": 123,
  "owned_by_user_id": 789,
  "deleted_at": null,
  "pipelineStage": { "id": 101, "name": "Qualified", "pipeline_id": 10, "rotting_days": 14 },
  "stageHistory": [
    { "id": 900, "deal_id": 55, "pipeline_stage_id": 101, "entered_at": "2026-04-01T09:00:00.000Z", "exited_at": null, "duration_seconds": null }
  ]
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No deal with this ID, it was deleted, or it belongs to an organization your key cannot access. |

<a id="deals--create"></a>

### Create a deal

Source: https://www.achieveapex.com/docs/api-reference/deals/create

Creates a deal in a pipeline stage.

#### Endpoint

`POST /deals`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the deal in. |
| `name` | string | Yes | Deal name. |
| `pipeline_id` | integer | Yes | Deal pipeline. Must be visible to the key's user. |
| `pipeline_stage_id` | integer | Yes | Stage in that pipeline. |
| `contact_id` | integer | Yes | Contact of the deal. |
| `amount` | number | No | Value. Default `0`. Overwritten when deal products change. |
| `currency_id` | integer | No | Currency. Fills the display fields and `exchange_rate`. |
| `status` | string | No | `open`, `won` or `lost`. |
| `company_id` | integer | No | Linked company. |
| `owned_by_user_id` | integer | No | Owner. |
| `expected_close_date` | string | No | ISO 8601 date-time. |
| `custom_fields_by_key` | object | No | Custom field values keyed by field `key`. |
| `tags` | array | No | `{ id }` of the organization's deal tags. |

Fields not in the [deal object](#deals) are rejected. `created_by_user_id` is set to the API key's user.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/deals \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Annual plan",
    "pipeline_id": 10,
    "pipeline_stage_id": 101,
    "contact_id": 123,
    "company_id": 101,
    "amount": 12000,
    "currency_id": 2,
    "status": "open",
    "expected_close_date": "2026-06-30T00:00:00.000Z",
    "tags": [{ "id": 3 }]
  }'
```

#### Response

```json
{
  "id": 55,
  "name": "Annual plan",
  "amount": "12000.00",
  "currency_id": 2,
  "exchange_rate": "1.000000",
  "currency_symbol": "$",
  "currency_format": "{symbol}{amount}",
  "decimal_places": 2,
  "thousand_separator": ",",
  "decimal_separator": ".",
  "status": "open",
  "expected_close_date": "2026-06-30T00:00:00.000Z",
  "won_date": null,
  "lost_date": null,
  "organization_id": 456,
  "pipeline_id": 10,
  "pipeline_stage_id": 101,
  "contact_id": 123,
  "company_id": 101,
  "created_by_user_id": 789,
  "owned_by_user_id": null,
  "tags": [{ "id": 3, "name": "Hot", "color": "#EF4444" }],
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null
}
```

Creating a deal records its first stage in the stage history and triggers the organization's "deal created" automations.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | A required field is missing, an unknown field is sent, or a custom field value is invalid. |
| `403 Forbidden` | `organization_id` is not accessible with your key, or `pipeline_id` is a private pipeline the key's user cannot see. |

<a id="deals--update"></a>

### Update a deal

Source: https://www.achieveapex.com/docs/api-reference/deals/update

Partially updates a deal. Use it to move a deal to another stage, mark it won or lost, or change its data.

#### Endpoint

`PATCH /deals/:id`

#### Body

Any writable field of the [deal object](#deals). Fields not in the object are rejected.

- `status: "won"` sets `won_date`; `status: "lost"` sets `lost_date`; `status: "open"` clears both dates and the lost reason.
- `deal_lost_reason_id` fills `deal_lost_reason` with the reason text.
- Changing `pipeline_stage_id` closes the current stage in the stage history and opens the new one.
- Changing `currency_id` recalculates `exchange_rate` unless you send it.
- `custom_fields_by_key` is merged with existing values; send a key with `null` to clear it.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/deals/55 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "lost",
    "deal_lost_reason_id": 4
  }'
```

#### Response

Returns the updated [deal object](#deals) with related data embedded (see [embedded data](#deals)).

```json
{
  "id": 55,
  "name": "Annual plan",
  "status": "lost",
  "won_date": null,
  "lost_date": "2026-05-02T16:20:00.000Z",
  "deal_lost_reason_id": 4,
  "deal_lost_reason": "Price too high",
  "pipeline_id": 10,
  "pipeline_stage_id": 101,
  "updated_at": "2026-05-02T16:20:00.000Z",
  "deleted_at": null,
  "pipelineStage": { "id": 101, "name": "Qualified", "pipeline_id": 10, "rotting_days": 14 }
}
```

Updating a deal triggers the organization's "deal updated" automations.

<a id="deals--delete"></a>

### Delete a deal

Source: https://www.achieveapex.com/docs/api-reference/deals/delete

Deletes a deal. This is a soft delete: the deal gets a `deleted_at` timestamp and no longer appears in list or get. Its activities are deleted too and its watchers are removed.

#### Endpoint

`DELETE /deals/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/deals/55 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [deal object](#deals) with `deleted_at` set.

```json
{
  "id": 55,
  "name": "Annual plan",
  "organization_id": 456,
  "deleted_at": "2026-05-03T08:00:00.000Z"
}
```

<a id="deals--errors"></a>

### Deals errors

Source: https://www.achieveapex.com/docs/api-reference/deals/errors

Errors use the standard Feathers error format.

```json
{
  "name": "Forbidden",
  "message": "You do not have access to this private pipeline.",
  "code": 403,
  "className": "forbidden"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query: missing required field, unknown field, invalid custom field key or value. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, the record belongs to an organization the key cannot access, or the pipeline is private and the key's user is not a member of it. |
| `404 Not Found` | The deal does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error. |

---

## Export data

<a id="export-data"></a>

### Export data overview

Source: https://www.achieveapex.com/docs/api-reference/export-data

Exports records of your organization (contacts, companies, deals, activities, products, campaign results) to a spreadsheet file. The export runs while the request is open and the response contains a `fileUrl` to download the file. Nothing is stored as an "export" record: this resource only has a create action.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/export-data` | [Export data](#export-data--create) |

Only organization **owners** and **admins** can export: the API key's user must have one of those roles in `organization_id`.

#### Export types

| `type` | What is exported | Extra body fields |
|---|---|---|
| `contacts` | Contacts with their main fields, tags, owner, company and one `cf_<key>` column per contact custom field. Files with more than 10,000 rows are CSV; smaller ones are Excel (`.xlsx`). | `view_id`, `filter`, `contact_ids` |
| `companies` | Companies with owner, creator, tags, contact count and custom fields (`.xlsx`). | `view_id`, `filter`, `company_ids`, `searchQuery` |
| `deals` | Deals with pipeline, stage, contact, company and custom fields (`.xlsx`). | `view_id`, `deal_ids` |
| `activities` | Activities (`.xlsx`). | `done`, `assigned_to_user_id` |
| `products` | Products of the catalog (`.xlsx`). | `product_ids`, `status`, `category_filter`, `searchQuery`, `include_variants` |
| `campaign-segment-contacts` | Contacts that match a [campaign segment](#campaign-segments). | `campaign_segment_id` (required) |
| `whatsapp-campaign-messages` | Messages of a WhatsApp campaign and their delivery status. | `campaign_id` (required) |
| `analytics-ai-conversations-job-result` | Results of an AI conversation analysis job. | `analytics_ai_conversations_job_id` (required) |

Exports are limited to 1,000,000 records. Deleted records are never exported.

#### The export result

```json
{
  "success": true,
  "total": 1520,
  "exported": 1520,
  "format": "xlsx",
  "fileUrl": "https://achieveapex-organization-files.s3.amazonaws.com/exports/contacts/456_contacts_2026-04-01T09-00-00-000Z.xlsx"
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `success` | boolean | `true` when the file was generated and uploaded. |
| `total` | integer | Records that matched the export. |
| `exported` | integer | Records written to the file. |
| `format` | string | `contacts` only: `xlsx` or `csv`. |
| `fileUrl` | string | Download URL of the generated file. |
| `segment_name` | string | `campaign-segment-contacts` only: name of the segment. |
| `segment_channel` | string | `campaign-segment-contacts` only: channel of the segment. |
| `campaign_name` | string | `whatsapp-campaign-messages` only: name of the campaign. |
| `campaign_status` | string | `whatsapp-campaign-messages` only: status of the campaign. |

#### Related

- [Contacts](#contacts)
- [Companies](#companies)
- [Deals](#deals)
- [Campaign segments: export contacts](#campaign-segments--export-contacts)

<a id="export-data--create"></a>

### Export data

Source: https://www.achieveapex.com/docs/api-reference/export-data/create

Generates a spreadsheet with the records of one type and returns its download URL. Large exports can take a while; keep the request open until it answers.

#### Endpoint

`POST /export-data`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to export from. The API key's user must be an owner or admin of it. |
| `type` | string | Yes | One of the [export types](#export-data). |
| `view_id` | integer | No | `contacts`, `companies`, `deals`: export only the records of this saved view. Takes precedence over the other filters. |
| `contact_ids` | integer[] | No | `contacts`: export only these contacts. |
| `company_ids` | integer[] | No | `companies`: export only these companies. |
| `deal_ids` | integer[] | No | `deals`: export only these deals. |
| `product_ids` | integer[] | No | `products`: export only these products. |
| `filter` | object | No | `contacts`: any of `searchTerm` (name or email), `company_id`, `system_type`, `owned_by_user_id`, `tag_ids`. `companies`: `searchTerm` (name). |
| `searchQuery` | string | No | `companies`, `products`: name search. |
| `done` | boolean | No | `activities`: only done or pending activities. |
| `assigned_to_user_id` | integer | No | `activities`: only activities assigned to this user. |
| `status` | string | No | `products`: only products with this status (`all` for every status). |
| `category_filter` | integer \| string | No | `products`: category ID, `0` for products without category, `all` for every category. |
| `include_variants` | boolean | No | `products`: include product variants. Default `false`. |
| `campaign_segment_id` | integer | For `campaign-segment-contacts` | Segment to export. |
| `campaign_id` | integer | For `whatsapp-campaign-messages` | WhatsApp campaign to export. |
| `analytics_ai_conversations_job_id` | integer | For `analytics-ai-conversations-job-result` | Analysis job to export. |

Without filters, every record of the type in the organization is exported.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/export-data \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "type": "contacts",
    "filter": { "system_type": "lead", "tag_ids": [7] }
  }'
```

#### Response

```json
{
  "success": true,
  "total": 320,
  "exported": 320,
  "format": "xlsx",
  "fileUrl": "https://achieveapex-organization-files.s3.amazonaws.com/exports/contacts/456_contacts_2026-04-01T09-00-00-000Z.xlsx"
}
```

#### Errors

Validation errors of this endpoint are returned as `500` with a descriptive `message`:

| Message | When |
|---|---|
| `Organization ID is required` | `organization_id` is missing. |
| `Only organization owners and admins can export data` | The key's user is a `member`. |
| `You do not have permission to export data from this organization` | The key's user does not belong to the organization. |
| `Campaign segment ID is required for this export type` (and similar) | A required ID for the chosen `type` is missing. |
| `Cannot export more than 1000000 ...` | Too many records. |

---

## Loyalty actions

<a id="loyalty-actions"></a>

### Loyalty actions overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions

Cashier and card operations: scan codes, register purchases, check in memberships, top up gift cards and share cards.

Every action is a `POST` to the same endpoint with an `action` name and the organization ID. These are the operations a point of sale, kiosk or app performs on a card.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/loyalty-actions` | [`scan`: resolve a card or reward code](#loyalty-actions--scan) |
| `POST` | `/loyalty-actions` | [`register_purchase`: register a purchase or visit](#loyalty-actions--register-purchase) |
| `POST` | `/loyalty-actions` | [`use_membership`: check in a membership](#loyalty-actions--use-membership) |
| `POST` | `/loyalty-actions` | [`load_balance`: top up a gift card](#loyalty-actions--load-balance) |
| `POST` | `/loyalty-actions` | [`wallet_links`: card page and wallet links](#loyalty-actions--wallet-links) |
| `POST` | `/loyalty-actions` | [`send_card`: email the card link](#loyalty-actions--send-card) |
| `POST` | `/loyalty-actions` | `refresh_pass` and `recompute_tiers` (see [Actions](#actions)) |

`organization_id` is required in every body and must be the API key's organization. There is no list, get, update or delete.

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "register_purchase",
    "member_id": 3001,
    "amount": 25.5,
    "reference": "POS-TICKET-10045"
  }'
```

#### Actions

| Action | Parameters | Does |
|--------|------------|------|
| [`scan`](#loyalty-actions--scan) | `code` | Finds a card (card code or referral code) or a reward code |
| [`register_purchase`](#loyalty-actions--register-purchase) | `member_id`, `amount`, `note`, `reference` | Registers a purchase or visit and awards points, stamps or cashback |
| [`use_membership`](#loyalty-actions--use-membership) | `member_id`, `note` | Uses one check-in of a membership |
| [`load_balance`](#loyalty-actions--load-balance) | `member_id`, `amount`, `description` | Tops up a gift card |
| [`wallet_links`](#loyalty-actions--wallet-links) | `member_id` | Returns the card page and the Apple Wallet / Google Wallet links |
| [`send_card`](#loyalty-actions--send-card) | `member_id` | Emails the card link to the customer |
| `refresh_pass` | `member_id` | Pushes the latest card data to the installed wallet passes. Returns `{ "refreshed": true }` |
| `recompute_tiers` | `program_id` | Re-evaluates the tier of every member of a program. Returns `{ "updated": <number of members changed> }` |

#### Common body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | One of the actions above |
| `member_id` | Number | Depends on the action | ID of the card ([Loyalty Members](#loyalty-members)). It must belong to your organization. |

An unknown action returns `400` with `"Unknown action. Use one of: scan, register_purchase, use_membership, load_balance, wallet_links, send_card, refresh_pass, recompute_tiers"`. A `member_id` of another organization returns `404` `"Member not found in this organization"`.

#### Response values

The `member` returned by these actions is the full [Loyalty Member object](#loyalty-members) (numbers as numbers). Amounts in `transaction` and `rewards` are numbers.

Every balance movement also refreshes the card in Apple Wallet and Google Wallet and fires the **Loyalty balance changed** automation trigger (and **Reward unlocked** / **Tier changed** when that happens).

<a id="loyalty-actions--wallet-links"></a>

### Get wallet links

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions/wallet-links

Get the links of a card: the private card page and the links to add the card to Apple Wallet and Google Wallet. Use them to show the card in your app or send it to the customer.

#### Endpoint

`POST /loyalty-actions` with `"action": "wallet_links"`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "wallet_links",
    "member_id": 3001
  }'
```

#### Response

```json
{
  "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
  "apple_url": "https://api.achieveapex.com/loyalty-wallet/apple/pass/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11.pkpass",
  "google_url": "https://api.achieveapex.com/loyalty-wallet/google/save/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
  "wallet_availability": { "apple": true, "google": true }
}
```

| Field | Description |
|-------|-------------|
| `card_url` | Private card page with the QR code, balance and rewards |
| `apple_url` | Downloads the Apple Wallet pass (`.pkpass`). `null` when Apple Wallet is not available |
| `google_url` | Opens the Google Wallet save page. `null` when Google Wallet is not available |
| `wallet_availability` | Which wallets are available on the platform |

These links give access to the card: only share them with the card owner.

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | `wallet_links` |
| `member_id` | Number | Yes | ID of the card |

<a id="loyalty-actions--load-balance"></a>

### Load gift card balance

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions/load-balance

Top up the balance of a gift card.

#### Endpoint

`POST /loyalty-actions` with `"action": "load_balance"`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "load_balance",
    "member_id": 3003,
    "amount": 50,
    "description": "Top-up at store #2"
  }'
```

#### Response

```json
{
  "member": {
    "id": 3003,
    "program_id": 15,
    "member_code": "M3QW8TRZ6N",
    "balance": 75,
    "card_url": "https://www.achieveapex.com/loyalty/card/1d7f2c9e-6b84-4a1f-9e35-0c4a8b2d7e61"
  },
  "transaction": {
    "id": 5123,
    "organization_id": 456,
    "program_id": 15,
    "member_id": 3003,
    "contact_id": 9003,
    "type": "load",
    "amount": 50,
    "balance_after": 75,
    "remaining_amount": 50,
    "expires_at": null,
    "source_type": "manual",
    "source_id": null,
    "description": "Top-up at store #2",
    "created_at": "2026-11-07T14:15:00.000Z"
  }
}
```

`member` is the full [Loyalty Member object](#loyalty-members) after the top-up (shortened above).

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | `load_balance` |
| `member_id` | Number | Yes | ID of a gift card |
| `amount` | Number | Yes | Amount to add, in the program currency. Must be greater than zero. |
| `description` | String | No | Description of the movement (defaults to `Gift card top-up`) |

This action has no idempotency key: send it once per top-up. To spend a gift card balance, create a [redemption with `amount`](#loyalty-redemptions--create).

#### Errors

| Message | Cause |
|---------|-------|
| `Only gift cards can be topped up` | The card belongs to a program that is not a `gift_card` |
| `Amount must be greater than zero` | `amount` is missing, zero or negative |

<a id="loyalty-actions--register-purchase"></a>

### Register a purchase

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions/register-purchase

Register an in-store purchase or visit on a card. The program's earning rules decide what the customer earns: points, stamps or cashback, including the tier multiplier.

#### Endpoint

`POST /loyalty-actions` with `"action": "register_purchase"`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "register_purchase",
    "member_id": 3001,
    "amount": 25.5,
    "note": "Store #2",
    "reference": "POS-TICKET-10045"
  }'
```

#### Response

```json
{
  "member": {
    "id": 3001,
    "program_id": 12,
    "member_code": "K7PX2M9QRT",
    "balance": 255,
    "lifetime_earned": 505,
    "lifetime_spend": 456,
    "visits_count": 15,
    "tier_id": null,
    "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
  },
  "transaction": {
    "id": 5121,
    "organization_id": 456,
    "program_id": 12,
    "member_id": 3001,
    "contact_id": 9001,
    "type": "earn",
    "amount": 25,
    "balance_after": 255,
    "remaining_amount": 25,
    "expires_at": "2027-11-07T14:05:00.000Z",
    "expired_at": null,
    "source_type": "pos",
    "source_id": "POS-TICKET-10045",
    "source_amount": 25.5,
    "description": "Store #2",
    "created_by_user_id": null,
    "metadata": null,
    "created_at": "2026-11-07T14:05:00.000Z",
    "updated_at": "2026-11-07T14:05:00.000Z",
    "deleted_at": null
  },
  "earned": 25,
  "duplicate": false
}
```

| Field | Description |
|-------|-------------|
| `member` | The card after the purchase (full [Loyalty Member object](#loyalty-members), shortened above) |
| `transaction` | The `earn` movement written to the ledger |
| `earned` | Points, stamps or cashback earned by this purchase |
| `duplicate` | `true` when the `reference` was already registered (see below) |

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | `register_purchase` |
| `member_id` | Number | Yes | ID of the card |
| `amount` | Number | No | Purchase amount in the program currency. `0` or empty registers a visit without amount. Cannot be negative. |
| `note` | String | No | Description of the movement (defaults to `In-store purchase` or `In-store visit`) |
| `reference` | String | No | Your ticket, receipt or order number (up to 60 characters). Makes the request idempotent. |

#### Idempotency

Send your own ticket or receipt number in `reference`. A purchase is registered once per program and `reference`: if you send the same `reference` again (for example after a timeout), nothing is added and the response returns the original `transaction` with `duplicate: true`. Without `reference`, every request registers a new purchase.

#### How much is earned

| Program type | Earned |
|--------------|--------|
| `stamps` | `earn_rules.stamps_per_visit` per purchase |
| `points` | `floor(amount / amount_step) * points_per_step + points_per_visit`, times the tier `earn_multiplier` |
| `cashback` | `amount * cashback_percent / 100`, times the tier `earn_multiplier` |

Nothing is earned when the purchase is below `earn_rules.min_amount`. Points and stamps balances are whole numbers (rounded down); cashback keeps two decimals. `transaction.amount` is the value actually credited. When tiers are enabled and a multiplier applies, `transaction.metadata.tier_multiplier` shows it.

Every registered purchase counts as a visit (`visits_count`) and adds `amount` to `lifetime_spend`. If the customer was referred, their first purchase also pays the referrer bonus.

#### Errors

| Message | Cause |
|---------|-------|
| `This card is blocked` | The card `status` is `blocked` |
| `This program does not earn from purchases` | Membership and gift card programs do not earn (use [`use_membership`](#loyalty-actions--use-membership) or [`load_balance`](#loyalty-actions--load-balance)) |
| `This program is not active` | The program is draft, paused or archived |
| `Amount cannot be negative` | `amount` is below zero |

<a id="loyalty-actions--scan"></a>

### Scan a code

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions/scan

Resolve a scanned or typed code: a card code (`member_code`), a referral code or a reward code issued by a redemption.

#### Endpoint

`POST /loyalty-actions` with `"action": "scan"`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "scan",
    "code": "K7PX2M9QRT"
  }'
```

#### Response

##### A card

```json
{
  "kind": "member",
  "member": {
    "id": 3001,
    "organization_id": 456,
    "program_id": 12,
    "contact_id": 9001,
    "status": "active",
    "member_code": "K7PX2M9QRT",
    "balance": 230,
    "tier_id": 4,
    "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567", "phone_country_code": "+1", "avatar_url": null },
    "tier": { "id": 4, "name": "Gold", "color": "#F59E0B", "earn_multiplier": 1.5 },
    "program": { "id": 12, "name": "Coffee Club", "type": "points", "currency_code": "USD", "stamps_required": null, "status": "active" },
    "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
  },
  "rewards": [
    {
      "id": 21,
      "name": "Free coffee",
      "description": "Any size",
      "cost": 100,
      "reward_type": "free_item",
      "discount_value": null,
      "min_tier_id": null,
      "stock": null,
      "redeemed_count": 37,
      "image_url": null
    }
  ]
}
```

`member` is the full [Loyalty Member object](#loyalty-members) (shortened above). `rewards` lists the active rewards of the card's program, cheapest first. To redeem one, see [Redeem a Reward](#loyalty-redemptions--create).

##### A reward code

```json
{
  "kind": "redemption",
  "redemption": {
    "id": 801,
    "organization_id": 456,
    "program_id": 12,
    "member_id": 3001,
    "contact_id": 9001,
    "reward_id": 21,
    "transaction_id": 5120,
    "code": "XH4K9PRT",
    "status": "issued",
    "cost": 100,
    "reward_name": "Free coffee",
    "reward_type": "free_item",
    "discount_value": null,
    "expires_at": "2026-12-07T14:00:00.000Z",
    "used_at": null,
    "channel": "public_page",
    "order_id": null,
    "created_at": "2026-11-07T14:00:00.000Z"
  },
  "member": { "id": 3001, "member_code": "K7PX2M9QRT", "balance": 130 }
}
```

Check `redemption.status` (`issued` can be handed over) and `expires_at`, then [mark it used](#loyalty-redemptions--update).

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | `scan` |
| `code` | String | Yes | The code. Case, spaces and dashes are ignored. |

If no card or reward code matches, the API returns `404` `"No card or reward code matches"`.

<a id="loyalty-actions--send-card"></a>

### Send the card link

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions/send-card

Email the card link to the customer and fire the **Loyalty card requested** automation trigger, so you can also deliver it by WhatsApp with an automation.

#### Endpoint

`POST /loyalty-actions` with `"action": "send_card"`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "send_card",
    "member_id": 3001
  }'
```

#### Response

```json
{
  "email": true,
  "has_email": true
}
```

| Field | Description |
|-------|-------------|
| `email` | `true` when the email was sent |
| `has_email` | Whether the contact has an email address |

The link is always sent to the email of the contact on file, never to another address. When the contact has no email, `email` and `has_email` are `false` and only the automation trigger runs.

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | `send_card` |
| `member_id` | Number | Yes | ID of the card |

<a id="loyalty-actions--use-membership"></a>

### Use a membership

Source: https://www.achieveapex.com/docs/api-reference/loyalty-actions/use-membership

Register one check-in on a membership card. Each check-in uses one of the card's remaining uses.

#### Endpoint

`POST /loyalty-actions` with `"action": "use_membership"`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-actions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "action": "use_membership",
    "member_id": 3002,
    "note": "Morning class"
  }'
```

#### Response

```json
{
  "member": {
    "id": 3002,
    "program_id": 14,
    "member_code": "P9RT4XKM2W",
    "balance": 7,
    "uses_remaining": 7,
    "visits_count": 3,
    "expires_at": "2026-12-01T16:00:00.000Z",
    "card_url": "https://www.achieveapex.com/loyalty/card/9b1e5c3a-27d4-4f60-8a3e-5d2c71f0a8b4"
  },
  "transaction": {
    "id": 5122,
    "organization_id": 456,
    "program_id": 14,
    "member_id": 3002,
    "contact_id": 9002,
    "type": "use",
    "amount": -1,
    "balance_after": 7,
    "remaining_amount": null,
    "expires_at": null,
    "source_type": "check_in",
    "source_id": null,
    "source_amount": null,
    "description": "Morning class",
    "created_at": "2026-11-07T14:10:00.000Z"
  }
}
```

`member` is the full [Loyalty Member object](#loyalty-members) after the check-in (shortened above).

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `action` | String | Yes | `use_membership` |
| `member_id` | Number | Yes | ID of a membership card |
| `note` | String | No | Description of the check-in (defaults to `Check-in`) |

#### Errors

| Message | Cause |
|---------|-------|
| `Only memberships have uses` | The card belongs to a program that is not a `membership` |
| `No uses left on this membership` | The balance is 0 |
| `This card is blocked` | The card `status` is `blocked` |
| `This card has expired` | The card `expires_at` has passed |

---

## Loyalty members

<a id="loyalty-members"></a>

### Loyalty members overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-members

A **loyalty member** is one customer's card in one program. A contact can have one card per program. Each card has a `member_code` (the code printed in its QR and scanned at the counter), a `balance` (points, stamps, money or uses depending on the program type) and a private `card_url` the customer can open on their phone or add to Apple Wallet / Google Wallet.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/loyalty-members` | [List or look up loyalty members](#loyalty-members--list) |
| `GET` | `/loyalty-members/:id` | [Get a loyalty member](#loyalty-members--get) |
| `POST` | `/loyalty-members` | [Enroll a loyalty member](#loyalty-members--create) |
| `PATCH` | `/loyalty-members/:id` | [Update a loyalty member](#loyalty-members--update) |
| `DELETE` | `/loyalty-members/:id` | [Delete a loyalty member](#loyalty-members--delete) |

The API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body on enroll.

#### The loyalty member object

```json
{
  "id": 3001,
  "organization_id": 456,
  "program_id": 12,
  "contact_id": 9001,
  "status": "active",
  "marketing_consent": false,
  "expires_at": null,
  "metadata": null,
  "member_code": "K7PX2M9QRT",
  "balance": 230,
  "lifetime_earned": 480,
  "lifetime_redeemed": 250,
  "lifetime_spend": 430.5,
  "visits_count": 14,
  "rewards_unlocked_count": 2,
  "tier_id": 4,
  "uses_remaining": null,
  "enrolled_at": "2026-11-01T16:00:00.000Z",
  "enrollment_source": "api",
  "referral_code": null,
  "referred_by_member_id": null,
  "consent_at": null,
  "last_activity_at": "2026-11-06T18:30:00.000Z",
  "last_visit_at": "2026-11-06T18:30:00.000Z",
  "wallet_serial": "4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
  "google_object_id": null,
  "google_object_synced_at": null,
  "apple_pass_updated_at": null,
  "apple_pass_installed_at": null,
  "google_pass_saved_at": null,
  "created_by_user_id": null,
  "created_at": "2026-11-01T16:00:00.000Z",
  "updated_at": "2026-11-06T18:30:00.000Z",
  "deleted_at": null,
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "5551234567",
    "phone_country_code": "+1",
    "avatar_url": null
  },
  "tier": { "id": 4, "name": "Gold", "color": "#F59E0B", "earn_multiplier": 1.5 },
  "program": {
    "id": 12,
    "name": "Coffee Club",
    "type": "points",
    "currency_code": "USD",
    "stamps_required": null,
    "status": "active"
  },
  "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization of the card. Required on enroll; cannot be changed. |
| `program_id` | integer | [Loyalty program](#loyalty-programs) of the card. Required on enroll; cannot be changed. |
| `contact_id` | integer | Contact who owns the card. A contact has one card per program. Cannot be changed. |
| `status` | string | One of `active`, `blocked`. A blocked card cannot earn, redeem or check in. |
| `marketing_consent` | boolean | The customer accepts marketing messages. |
| `expires_at` | string (date-time) \| null | Card expiry (memberships with `membership_validity_days`). `null` = no expiry. |
| `metadata` | object \| null | Extra data stored on the card. `metadata.birthday` (`MM-DD`) is used for the program `birthday_bonus`. |
| `member_code` | string | Read-only. Card code shown in the card QR. Use it with [`lookup`](#loyalty-members--list) or the [`scan`](#loyalty-actions--scan) action. |
| `balance` | number | Read-only. Current balance: points, stamps, money (cashback / gift card) or uses left (membership). Changed only through [actions](#loyalty-actions), [redemptions](#loyalty-redemptions) and [adjustments](#loyalty-transactions--create). |
| `lifetime_earned` | number | Read-only. Total earned since enrollment. |
| `lifetime_redeemed` | number | Read-only. Total redeemed since enrollment. |
| `lifetime_spend` | number | Read-only. Total purchase amount registered on the card. |
| `visits_count` | integer | Read-only. Qualifying purchases or visits. |
| `rewards_unlocked_count` | integer | Read-only. Number of times the balance went up to (or past) the cost of an active reward. |
| `tier_id` | integer \| null | Read-only. Current [tier](#loyalty-tiers), when the program has tiers. |
| `uses_remaining` | integer \| null | Read-only. Uses left on a membership. |
| `enrolled_at` | string (date-time) | Read-only. Enrollment time. |
| `enrollment_source` | string | How the card was created: `public_page`, `manual`, `checkout`, `automation`, `api`, `import`, `ai_assistant`, `referral` or `purchase`. Cards created with an API key get `api` unless you send another value. |
| `referral_code` | string \| null | Read-only. The member's own code to invite friends (programs with referrals). |
| `referred_by_member_id` | integer \| null | Read-only. Member who invited this customer. |
| `consent_at` | string (date-time) \| null | Read-only. When marketing consent was given. |
| `last_activity_at` | string (date-time) \| null | Read-only. Last balance movement. |
| `last_visit_at` | string (date-time) \| null | Read-only. Last qualifying purchase or visit. |
| `wallet_serial` | string | Read-only. Public identifier of the card used in `card_url` and the wallet pass links. |
| `google_object_id` | string \| null | Read-only. Google Wallet object of the card. |
| `google_object_synced_at` | string (date-time) \| null | Read-only. Last sync with Google Wallet. |
| `apple_pass_updated_at` | string (date-time) \| null | Read-only. Last update of the Apple Wallet pass. |
| `apple_pass_installed_at` | string (date-time) \| null | Read-only. When the card was added to Apple Wallet. |
| `google_pass_saved_at` | string (date-time) \| null | Read-only. When the card was saved to Google Wallet. |
| `created_by_user_id` | integer \| null | Read-only. User who enrolled the card (`null` for API keys). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the card is deleted. |
| `contact` | object \| null | Read-only, added to every response: `id`, `first_name`, `last_name`, `email`, `phone`, `phone_country_code`, `avatar_url`. |
| `tier` | object \| null | Read-only, added: `id`, `name`, `color`, `earn_multiplier`. |
| `program` | object \| null | Read-only, added: `id`, `name`, `type`, `currency_code`, `stamps_required`, `status`. |
| `card_url` | string \| null | Read-only, added. Private card page. Anyone with this link can see the card, so only share it with the card owner. |

The card's wallet authentication token is never returned.

#### Related

To register purchases, check-ins and gift card top-ups on a card, see [Loyalty Actions](#loyalty-actions). For the balance history, see [Loyalty Transactions](#loyalty-transactions).

<a id="loyalty-members--list"></a>

### List or look up loyalty members

Source: https://www.achieveapex.com/docs/api-reference/loyalty-members/list

Retrieve the loyalty cards of your organization, or find one card by phone, email or card code.

#### Endpoint

`GET /loyalty-members`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | No | ID of your organization. Required when you use `lookup` or `search` (without it they are ignored). Results are always filtered to the API key's organization. |
| `lookup` | string | No | Exact card code or referral code, email, or phone number |
| `search` | string | No | Partial search on contact name, email, phone (4+ digits) or card code |
| `program_id` | number | No | Only cards of this program |
| `contact_id` | number | No | Only cards of this contact |
| `status` | string | No | `active` or `blocked` |
| `tier_id` | number | No | Only cards in this tier |
| `$limit` | number | No | Number of cards to return (default: 10, max: 50) |
| `$skip` | number | No | Number of cards to skip (for pagination) |
| `$sort` | object | No | Sort criteria, e.g. `$sort[last_activity_at]=-1` or `$sort[balance]=-1` |

#### Request

##### Find a card at the counter (`lookup`)

```bash
curl -G https://integrations.achieveapex.com/loyalty-members \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'program_id=12' \
  --data-urlencode 'lookup=jane@example.com'
```

`lookup` matches, in this order:

1. The exact card code (`member_code`) or referral code (case and spaces are ignored).
2. An email address (exact match on the contact email) when the value contains `@`.
3. A phone number (at least 6 digits), with or without the country code.

A contact can have one card per program, so a lookup can return several cards when the organization has several programs. Add `program_id` to get only the card of one program.

##### List and search

```bash
curl -G https://integrations.achieveapex.com/loyalty-members \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'program_id=12' \
  --data-urlencode 'status=active' \
  --data-urlencode 'search=jane' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$skip=0' \
  --data-urlencode '$sort[last_activity_at]=-1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 3001,
      "organization_id": 456,
      "program_id": 12,
      "contact_id": 9001,
      "status": "active",
      "member_code": "K7PX2M9QRT",
      "balance": 230,
      "lifetime_earned": 480,
      "lifetime_redeemed": 250,
      "lifetime_spend": 430.5,
      "visits_count": 14,
      "tier_id": 4,
      "uses_remaining": null,
      "expires_at": null,
      "enrollment_source": "api",
      "last_activity_at": "2026-11-06T18:30:00.000Z",
      "wallet_serial": "4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
      "contact": {
        "id": 9001,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "phone": "5551234567",
        "phone_country_code": "+1",
        "avatar_url": null
      },
      "tier": { "id": 4, "name": "Gold", "color": "#F59E0B", "earn_multiplier": 1.5 },
      "program": {
        "id": 12,
        "name": "Coffee Club",
        "type": "points",
        "currency_code": "USD",
        "stamps_required": null,
        "status": "active"
      },
      "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
    }
  ]
}
```

Each item contains every field of the [Loyalty Member object](#loyalty-members) (the example above is shortened). When nothing matches, `data` is an empty list.

When both `lookup` and `search` are sent, only `lookup` is used.

<a id="loyalty-members--get"></a>

### Get a loyalty member

Source: https://www.achieveapex.com/docs/api-reference/loyalty-members/get

Retrieve a single loyalty card by ID.

#### Endpoint

`GET /loyalty-members/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/loyalty-members/3001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the full [Loyalty Member object](#loyalty-members) with `contact`, `tier`, `program` and `card_url`.

```json
{
  "id": 3001,
  "organization_id": 456,
  "program_id": 12,
  "contact_id": 9001,
  "status": "active",
  "marketing_consent": false,
  "expires_at": null,
  "metadata": null,
  "member_code": "K7PX2M9QRT",
  "balance": 230,
  "lifetime_earned": 480,
  "lifetime_redeemed": 250,
  "lifetime_spend": 430.5,
  "visits_count": 14,
  "rewards_unlocked_count": 2,
  "tier_id": 4,
  "uses_remaining": null,
  "enrolled_at": "2026-11-01T16:00:00.000Z",
  "enrollment_source": "api",
  "referral_code": null,
  "referred_by_member_id": null,
  "consent_at": null,
  "last_activity_at": "2026-11-06T18:30:00.000Z",
  "last_visit_at": "2026-11-06T18:30:00.000Z",
  "wallet_serial": "4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
  "google_object_id": null,
  "google_object_synced_at": null,
  "apple_pass_updated_at": null,
  "apple_pass_installed_at": null,
  "google_pass_saved_at": null,
  "created_by_user_id": null,
  "created_at": "2026-11-01T16:00:00.000Z",
  "updated_at": "2026-11-06T18:30:00.000Z",
  "deleted_at": null,
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "5551234567",
    "phone_country_code": "+1",
    "avatar_url": null
  },
  "tier": { "id": 4, "name": "Gold", "color": "#F59E0B", "earn_multiplier": 1.5 },
  "program": {
    "id": 12,
    "name": "Coffee Club",
    "type": "points",
    "currency_code": "USD",
    "stamps_required": null,
    "status": "active"
  },
  "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
}
```

<a id="loyalty-members--create"></a>

### Enroll a loyalty member

Source: https://www.achieveapex.com/docs/api-reference/loyalty-members/create

Enroll a customer in a loyalty program and get their card. Use an existing contact (`contact_id`) or send the customer's details (`contact`) and AchieveApex finds the contact by email or phone, or creates it.

#### Endpoint

`POST /loyalty-members`

#### Request

##### With customer details

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-members \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "program_id": 12,
    "contact": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "5551234567",
      "phone_country_code": "+1",
      "phone_country_iso": "US"
    },
    "marketing_consent": true
  }'
```

##### With an existing contact

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-members \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "program_id": 12,
    "contact_id": 9001
  }'
```

#### Response

```json
{
  "id": 3001,
  "organization_id": 456,
  "program_id": 12,
  "contact_id": 9001,
  "status": "active",
  "marketing_consent": true,
  "expires_at": null,
  "metadata": null,
  "member_code": "K7PX2M9QRT",
  "balance": 50,
  "lifetime_earned": 50,
  "lifetime_redeemed": 0,
  "lifetime_spend": 0,
  "visits_count": 0,
  "rewards_unlocked_count": 0,
  "tier_id": null,
  "uses_remaining": null,
  "enrolled_at": "2026-11-07T14:00:00.000Z",
  "enrollment_source": "api",
  "referral_code": null,
  "referred_by_member_id": null,
  "consent_at": "2026-11-07T14:00:00.000Z",
  "last_activity_at": "2026-11-07T14:00:00.000Z",
  "last_visit_at": null,
  "wallet_serial": "4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
  "created_at": "2026-11-07T14:00:00.000Z",
  "updated_at": "2026-11-07T14:00:00.000Z",
  "deleted_at": null,
  "already_enrolled": false,
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "5551234567",
    "phone_country_code": "+1",
    "avatar_url": null
  },
  "tier": null,
  "program": {
    "id": 12,
    "name": "Coffee Club",
    "type": "points",
    "currency_code": "USD",
    "stamps_required": null,
    "status": "active"
  },
  "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
}
```

The response is the [Loyalty Member object](#loyalty-members) plus `already_enrolled`. Send `card_url` to the customer (or use the [`send_card`](#loyalty-actions--send-card) action) so they can open the card and add it to their wallet.

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `program_id` | Number | Yes | ID of the loyalty program |
| `contact_id` | Number | One of `contact_id` / `contact` | ID of an existing contact of your organization |
| `contact` | Object | One of `contact_id` / `contact` | Customer details: `first_name`, `last_name`, `email`, `phone`, `phone_country_code`, `phone_country_iso`. An email or a phone is required. |
| `marketing_consent` | Boolean | No | The customer accepted marketing messages (stores `consent_at`) |
| `referral_code` | String | No | Referral code of the member who invited this customer (programs with referrals) |
| `initial_amount` | Number | No | Gift cards: opening balance. Defaults to the program `gift_card_default_amount` |
| `metadata` | Object | No | Extra data stored on the card |
| `enrollment_source` | String | No | Defaults to `api` for API key requests |

#### Behavior

- **Idempotent:** a contact has one card per program. Enrolling the same contact again returns the existing card unchanged with `already_enrolled: true`, so it is safe to retry.
- **Contact matching:** with `contact`, the contact is found by email first, then by phone (with or without the country code). Empty fields of an existing contact (name, email, phone) are filled with the values you send; existing values are never overwritten. If no contact matches, a new one is created.
- **Opening movements** on a new card: the program `welcome_bonus` (points, stamps and cashback), the membership uses (`membership_uses`) or the gift card balance, and the referral bonus when a valid `referral_code` is sent.
- Enrolling a new card fires the **Member enrolled** automation trigger.
- Errors: `"contact_id or contact is required"`, `"Email or phone is required"`, `"Invalid email"`, `"This program is archived"` (400) and `"Loyalty program not found"` (404).

<a id="loyalty-members--update"></a>

### Update a loyalty member

Source: https://www.achieveapex.com/docs/api-reference/loyalty-members/update

Block or reactivate a card, change its expiry, consent or metadata. Balances cannot be changed here: use [Loyalty Actions](#loyalty-actions) or a [manual adjustment](#loyalty-transactions--create).

#### Endpoint

`PATCH /loyalty-members/:id`

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/loyalty-members/3001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "blocked"
  }'
```

#### Response

```json
{
  "id": 3001,
  "organization_id": 456,
  "program_id": 12,
  "contact_id": 9001,
  "status": "blocked",
  "marketing_consent": true,
  "expires_at": null,
  "metadata": null,
  "member_code": "K7PX2M9QRT",
  "balance": 230,
  "lifetime_earned": 480,
  "lifetime_redeemed": 250,
  "lifetime_spend": 430.5,
  "visits_count": 14,
  "tier_id": 4,
  "enrollment_source": "api",
  "wallet_serial": "4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11",
  "updated_at": "2026-11-07T15:00:00.000Z",
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "5551234567",
    "phone_country_code": "+1",
    "avatar_url": null
  },
  "tier": { "id": 4, "name": "Gold", "color": "#F59E0B", "earn_multiplier": 1.5 },
  "program": {
    "id": 12,
    "name": "Coffee Club",
    "type": "points",
    "currency_code": "USD",
    "stamps_required": null,
    "status": "active"
  },
  "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
}
```

Returns the updated [Loyalty Member object](#loyalty-members) (shortened above).

#### Body parameters

| Name | Type | Description |
|---|---|---|
| `status` | String | `active` or `blocked`. A blocked card cannot earn, redeem or check in. |
| `expires_at` | String \| null | ISO 8601 expiry date of the card, or `null` for no expiry |
| `marketing_consent` | Boolean | Whether the customer accepts marketing messages |
| `metadata` | Object \| null | Extra data stored on the card. Replaces the whole object. `metadata.birthday` (`MM-DD`) is used for the program `birthday_bonus`. |

Other fields are read-only. Changing `status` or `expires_at` also refreshes the card in Apple Wallet and Google Wallet.

<a id="loyalty-members--delete"></a>

### Delete a loyalty member

Source: https://www.achieveapex.com/docs/api-reference/loyalty-members/delete

Delete a loyalty card. This is a soft delete: the card gets `deleted_at`, no longer appears in list or get, and stops working. To stop a card temporarily, [block it](#loyalty-members--update) with `"status": "blocked"` instead.

#### Endpoint

`DELETE /loyalty-members/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/loyalty-members/3001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [loyalty member](#loyalty-members) with `deleted_at` set (and `contact`, `tier`, `program`, `card_url`).

```json
{
  "id": 3001,
  "organization_id": 456,
  "program_id": 12,
  "contact_id": 9001,
  "status": "active",
  "member_code": "K7PX2M9QRT",
  "balance": 230,
  "deleted_at": "2026-11-08T10:00:00.000Z",
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "5551234567",
    "phone_country_code": "+1",
    "avatar_url": null
  },
  "tier": null,
  "program": {
    "id": 12,
    "name": "Coffee Club",
    "type": "points",
    "currency_code": "USD",
    "stamps_required": null,
    "status": "active"
  },
  "card_url": "https://www.achieveapex.com/loyalty/card/4f0c2a7e-9a51-4d8e-a6a1-2a8d0f3b9c11"
}
```

(Shortened: the response contains every field of the member object.)

#### Side effects

- The card is set to `blocked` (after the response is built, so the response still shows the previous `status`) and its Apple Wallet and Google Wallet passes are refreshed so they stop working.
- The program `member_count` goes down by one.
- The card's [transactions](#loyalty-transactions) are kept and still listed.

---

## Loyalty programs

<a id="loyalty-programs"></a>

### Loyalty programs overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-programs

A **loyalty program** is a card your customers carry: a stamp card, a points program, cashback, a membership (a pack of uses) or a gift card. Each customer gets one **member** card per program. Programs are usually configured in the Loyalty app; through the API you read them to know their ID, type, currency and enrollment link, and you can also create and configure them.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/loyalty-programs` | [List loyalty programs](#loyalty-programs--list) |
| `GET` | `/loyalty-programs/:id` | [Get a loyalty program](#loyalty-programs--get) |
| `POST` | `/loyalty-programs` | [Create a loyalty program](#loyalty-programs--create) |
| `PATCH` | `/loyalty-programs/:id` | [Update a loyalty program](#loyalty-programs--update) |
| `DELETE` | `/loyalty-programs/:id` | [Delete a loyalty program](#loyalty-programs--delete) |

All requests use your API key in the `x-api-key` header (see [Authentication](#authentication)). An API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body when you create records. Records of other organizations are never returned (lists come back empty and direct access returns `404`).

#### Loyalty API at a glance

| Step | Endpoint |
|------|----------|
| Find the program ID | [`GET /loyalty-programs`](#loyalty-programs--list) |
| Enroll a customer (idempotent) | [`POST /loyalty-members`](#loyalty-members--create) |
| Find a card by phone, email or card code | [`GET /loyalty-members?lookup=`](#loyalty-members--list) |
| Scan a card or reward QR code | [`POST /loyalty-actions` `scan`](#loyalty-actions--scan) |
| Register a purchase or visit | [`POST /loyalty-actions` `register_purchase`](#loyalty-actions--register-purchase) |
| Redeem a reward or balance | [`POST /loyalty-redemptions`](#loyalty-redemptions--create) |
| Mark a reward code used or cancel it | [`PATCH /loyalty-redemptions/:id`](#loyalty-redemptions--update) |
| Manual balance adjustment | [`POST /loyalty-transactions`](#loyalty-transactions--create) |
| Balance history | [`GET /loyalty-transactions`](#loyalty-transactions--list) |
| Card page and Apple / Google Wallet links | [`POST /loyalty-actions` `wallet_links`](#loyalty-actions--wallet-links) |
| KPIs | [`GET /loyalty-reports`](#loyalty-reports) |

#### The loyalty program object

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Coffee Club",
  "description": "Earn points on every purchase",
  "type": "points",
  "status": "active",
  "slug": "coffee-club",
  "currency_code": "USD",
  "earn_rules": {
    "sources": { "orders": true, "invoices": true, "reservations": true, "events": false },
    "amount_step": 1,
    "points_per_step": 1,
    "stamps_per_visit": 1,
    "min_amount": 0,
    "points_per_visit": 0,
    "auto_enroll": false
  },
  "stamps_required": null,
  "cashback_percent": null,
  "welcome_bonus": 50,
  "birthday_bonus": 0,
  "referrals_enabled": false,
  "referrer_bonus": 0,
  "referred_bonus": 0,
  "expiration_days": 365,
  "min_redeem_amount": null,
  "membership_uses": null,
  "membership_validity_days": null,
  "gift_card_default_amount": null,
  "tiers_enabled": true,
  "tier_basis": "lifetime_points",
  "card_design": {
    "background_color": "#111827",
    "foreground_color": "#FFFFFF",
    "label_color": "#9CA3AF",
    "accent_color": "#F59E0B",
    "logo_url": null,
    "icon_url": null,
    "strip_image_url": null,
    "stamp_icon": "star"
  },
  "locations": null,
  "enrollment_settings": null,
  "terms": null,
  "public_enrollment_enabled": true,
  "apple_wallet_enabled": true,
  "google_wallet_enabled": true,
  "google_class_id": null,
  "google_class_synced_at": null,
  "member_count": 128,
  "created_by_user_id": 789,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-05T10:20:00.000Z",
  "deleted_at": null,
  "enrollment_url": "https://www.achieveapex.com/l/456/coffee-club",
  "wallet_availability": { "apple": true, "google": true }
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the program. Required on create; cannot be changed. |
| `name` | string | Program name (1 to 255 characters). Required on create. |
| `description` | string \| null | Description (up to 5000 characters). |
| `type` | string | One of `stamps`, `points`, `cashback`, `membership`, `gift_card` (see [Program types](#program-types)). Required on create; cannot be changed. |
| `status` | string | One of `draft`, `active`, `paused`, `archived`. Default `draft`. |
| `slug` | string | Link name used in `enrollment_url` (up to 80 characters), unique per organization. Generated from `name` when omitted. |
| `currency_code` | string \| null | Currency (for example `USD`). Purchases only earn by amount in this currency. Required to activate `cashback` and `gift_card` programs. |
| `earn_rules` | object \| null | How purchases and visits earn: `sources` (`orders`, `invoices`, `reservations`, `events` booleans), `amount_step`, `points_per_step`, `stamps_per_visit`, `min_amount`, `points_per_visit` (non-negative numbers; `amount_step` greater than 0) and `auto_enroll` (enroll the buyer on the first qualifying purchase). Sent keys are merged with the current rules. |
| `stamps_required` | integer \| null | Stamps programs: stamps for a full card, 2 to 30. Default `10`. |
| `cashback_percent` | number \| null | Cashback programs: percentage of the purchase returned, greater than 0 and up to 100. Default `5`. |
| `welcome_bonus` | number | Balance given on enrollment (points, stamps or cashback). Default `0`. |
| `birthday_bonus` | number | Balance given on the member's birthday (`metadata.birthday` of the member, `MM-DD`). Default `0`. |
| `referrals_enabled` | boolean | Members can invite friends with their `referral_code` (points, stamps and cashback only). Default `false`. |
| `referrer_bonus` | number | Bonus for the member who invited. Default `0`. |
| `referred_bonus` | number | Bonus for the invited member. Default `0`. |
| `expiration_days` | integer \| null | Days after which earned balance expires (at least 1). `null` = never. |
| `min_redeem_amount` | number \| null | Cashback: minimum amount per redemption. |
| `membership_uses` | integer \| null | Membership: uses granted on enrollment (at least 1). Default `10`. |
| `membership_validity_days` | integer \| null | Membership: days the card is valid after enrollment (sets the member `expires_at`). |
| `gift_card_default_amount` | number \| null | Gift cards: opening balance when no `initial_amount` is sent on enrollment. |
| `tiers_enabled` | boolean | Members are placed in [tiers](#loyalty-tiers) (points, stamps and cashback only). Default `false`. |
| `tier_basis` | string \| null | What tiers measure: `lifetime_points`, `lifetime_spend` or `visits`. Default `lifetime_points` for points programs. |
| `card_design` | object \| null | Card colors (`background_color`, `foreground_color`, `label_color`, `accent_color` as `#RRGGBB`), images (`logo_url`, `icon_url`, `strip_image_url`) and `stamp_icon`. Sent keys are merged with the current design. |
| `locations` | array \| null | Up to 10 store locations shown by wallet passes: `name`, `address`, `latitude`, `longitude`, `relevant_text`. |
| `enrollment_settings` | object \| null | Public enrollment page options: `ask_birthday`, `require_email`, `require_phone` (default `true`), `consent_text`, `headline`, `success_message`. |
| `terms` | string \| null | Terms and conditions (up to 10000 characters). |
| `public_enrollment_enabled` | boolean | Customers can join on the public `enrollment_url`. Default `true`. |
| `apple_wallet_enabled` | boolean | Offer the Apple Wallet pass. Default `true`. |
| `google_wallet_enabled` | boolean | Offer the Google Wallet pass. Default `true`. |
| `google_class_id` | string \| null | Read-only. Google Wallet class of the program. |
| `google_class_synced_at` | string (date-time) \| null | Read-only. Last sync of the Google Wallet class. |
| `member_count` | integer | Read-only. Number of members. |
| `created_by_user_id` | integer \| null | Read-only. User who created the program (`null` for API keys). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the program is deleted. |
| `enrollment_url` | string | Read-only, calculated. Public page where customers join (`/l/{organization_id}/{slug}`). |
| `wallet_availability` | object | Read-only, calculated. Whether Apple Wallet and Google Wallet passes are available on the platform (`apple`, `google`). |

##### Program types

| Value | Balance | How customers earn or use it |
|-------|---------|------------------------------|
| `stamps` | Stamps | `earn_rules.stamps_per_visit` stamps per qualifying visit; a full card has `stamps_required` stamps. |
| `points` | Points | `floor(amount / earn_rules.amount_step) * earn_rules.points_per_step`, plus `earn_rules.points_per_visit` per visit. |
| `cashback` | Money (`currency_code`) | `cashback_percent` of the purchase amount. Spent by amount. |
| `membership` | Uses left | Starts with `membership_uses`; each check-in uses one. |
| `gift_card` | Money (`currency_code`) | Loaded on enrollment (`gift_card_default_amount`) or with a top-up. Spent by amount. |

Purchases only earn by amount when they are in the program `currency_code`. `earn_rules.min_amount` sets a minimum purchase. When tiers are enabled, points and cashback earned are multiplied by the member tier `earn_multiplier` (stamps are not multiplied).

##### Status values

| Value | Description |
|-------|-------------|
| `draft` | Being configured. |
| `active` | Live: members earn and redeem. |
| `paused` | Temporarily stopped. |
| `archived` | Closed. New members cannot be enrolled. |


#### Events in your systems

Loyalty events can be sent to your own systems with **Automations**: create an automation with a **Loyalty Events** trigger and add an **HTTP** node that calls your endpoint. Available triggers: member enrolled, loyalty balance changed, reward unlocked, reward redeemed, tier changed, card requested, member inactive and balance expiring. The trigger data includes the contact, the program, the member (code, balance, tier) and the card URL, which you can map into the HTTP request.

#### Error Handling

The Loyalty API returns standard HTTP status codes. Business rules return `400 Bad Request` with a readable message, for example `"Not enough balance for this reward"`, `"This reward requires the Gold tier"`, `"This card is blocked"` or `"This program is not active"`.

```json
{
  "name": "BadRequest",
  "message": "Not enough balance for this reward",
  "code": 400,
  "className": "bad-request"
}
```

| Status Code | Description |
|-------------|-------------|
| `400 Bad Request` | Invalid data or a business rule was not met |
| `401 Unauthorized` | Missing or invalid API key |
| `403 Forbidden` | The `organization_id` sent is not the API key's organization |
| `404 Not Found` | Program, member, reward or code not found (also for records of other organizations) |
| `429 Too Many Requests` | Rate limit exceeded (see [Authentication](#authentication)) |
| `500 Internal Server Error` | Server error |

#### Related

[Loyalty Members](#loyalty-members), [Loyalty Actions](#loyalty-actions), [Loyalty Transactions](#loyalty-transactions), [Loyalty Redemptions](#loyalty-redemptions), [Loyalty Rewards](#loyalty-rewards), [Loyalty Tiers](#loyalty-tiers) and [Loyalty Reports](#loyalty-reports).

<a id="loyalty-programs--list"></a>

### List loyalty programs

Source: https://www.achieveapex.com/docs/api-reference/loyalty-programs/list

Retrieve the loyalty programs of your organization with optional filtering, search and pagination.

#### Endpoint

`GET /loyalty-programs`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | No | ID of your organization. Optional: results are always filtered to the API key's organization. |
| `status` | string | No | Filter by status: `draft`, `active`, `paused` or `archived` |
| `type` | string | No | Filter by type: `stamps`, `points`, `cashback`, `membership` or `gift_card` |
| `slug` | string | No | Filter by the program link name |
| `search` | string | No | Case-insensitive search on the program name and slug |
| `$limit` | number | No | Number of programs to return (default: 10, max: 50) |
| `$skip` | number | No | Number of programs to skip (for pagination) |
| `$sort` | object | No | Sort criteria, e.g. `$sort[created_at]=-1` for newest first |

#### Request

```bash
curl -G https://integrations.achieveapex.com/loyalty-programs \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'status=active' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$skip=0' \
  --data-urlencode '$sort[created_at]=-1'
```

#### Response

```json
{
  "total": 2,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 12,
      "organization_id": 456,
      "name": "Coffee Club",
      "description": "Earn points on every purchase",
      "type": "points",
      "status": "active",
      "slug": "coffee-club",
      "currency_code": "USD",
      "stamps_required": null,
      "cashback_percent": null,
      "welcome_bonus": 50,
      "expiration_days": 365,
      "tiers_enabled": true,
      "tier_basis": "lifetime_points",
      "public_enrollment_enabled": true,
      "apple_wallet_enabled": true,
      "google_wallet_enabled": true,
      "member_count": 128,
      "created_at": "2026-11-01T15:00:00.000Z",
      "updated_at": "2026-11-05T10:20:00.000Z",
      "deleted_at": null,
      "enrollment_url": "https://www.achieveapex.com/l/456/coffee-club",
      "wallet_availability": { "apple": true, "google": true }
    },
    {
      "id": 13,
      "organization_id": 456,
      "name": "Stamp Card",
      "description": null,
      "type": "stamps",
      "status": "active",
      "slug": "stamp-card",
      "currency_code": "USD",
      "stamps_required": 10,
      "cashback_percent": null,
      "welcome_bonus": 0,
      "expiration_days": null,
      "tiers_enabled": false,
      "tier_basis": null,
      "public_enrollment_enabled": true,
      "apple_wallet_enabled": true,
      "google_wallet_enabled": true,
      "member_count": 54,
      "created_at": "2026-11-02T09:00:00.000Z",
      "updated_at": "2026-11-02T09:00:00.000Z",
      "deleted_at": null,
      "enrollment_url": "https://www.achieveapex.com/l/456/stamp-card",
      "wallet_availability": { "apple": true, "google": true }
    }
  ]
}
```

Each item contains every field of the [Loyalty Program object](#loyalty-programs) (the example above is shortened).

<a id="loyalty-programs--get"></a>

### Get a loyalty program

Source: https://www.achieveapex.com/docs/api-reference/loyalty-programs/get

Retrieve a single loyalty program by ID.

#### Endpoint

`GET /loyalty-programs/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/loyalty-programs/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the full [Loyalty Program object](#loyalty-programs), including the calculated `enrollment_url` and `wallet_availability`.

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Coffee Club",
  "description": "Earn points on every purchase",
  "type": "points",
  "status": "active",
  "slug": "coffee-club",
  "currency_code": "USD",
  "earn_rules": {
    "sources": { "orders": true, "invoices": true, "reservations": true, "events": false },
    "amount_step": 1,
    "points_per_step": 1,
    "stamps_per_visit": 1,
    "min_amount": 0,
    "points_per_visit": 0,
    "auto_enroll": false
  },
  "stamps_required": null,
  "cashback_percent": null,
  "welcome_bonus": 50,
  "birthday_bonus": 0,
  "referrals_enabled": false,
  "referrer_bonus": 0,
  "referred_bonus": 0,
  "expiration_days": 365,
  "min_redeem_amount": null,
  "membership_uses": null,
  "membership_validity_days": null,
  "gift_card_default_amount": null,
  "tiers_enabled": true,
  "tier_basis": "lifetime_points",
  "card_design": {
    "background_color": "#111827",
    "foreground_color": "#FFFFFF",
    "label_color": "#9CA3AF",
    "accent_color": "#F59E0B",
    "logo_url": null,
    "icon_url": null,
    "strip_image_url": null,
    "stamp_icon": "star"
  },
  "locations": null,
  "enrollment_settings": null,
  "terms": null,
  "public_enrollment_enabled": true,
  "apple_wallet_enabled": true,
  "google_wallet_enabled": true,
  "google_class_id": null,
  "google_class_synced_at": null,
  "member_count": 128,
  "created_by_user_id": 789,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-05T10:20:00.000Z",
  "deleted_at": null,
  "enrollment_url": "https://www.achieveapex.com/l/456/coffee-club",
  "wallet_availability": { "apple": true, "google": true }
}
```

<a id="loyalty-programs--create"></a>

### Create a loyalty program

Source: https://www.achieveapex.com/docs/api-reference/loyalty-programs/create

Create a stamp card, points program, cashback program, membership or gift card. New programs start as `draft`: activate them with `"status": "active"` (here or later with an update).

#### Endpoint

`POST /loyalty-programs`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `name` | string | Yes | Program name (1 to 255 characters). |
| `type` | string | Yes | `stamps`, `points`, `cashback`, `membership` or `gift_card`. Cannot be changed later. |
| `status` | string | No | `draft` (default), `active`, `paused` or `archived`. |
| `slug` | string | No | Link name for the public enrollment page. Generated from `name` when omitted. |
| `currency_code` | string | No | Currency, for example `USD`. Required before a `cashback` or `gift_card` program can be `active`. |
| `description`, `earn_rules`, `stamps_required`, `cashback_percent`, `welcome_bonus`, `birthday_bonus`, `referrals_enabled`, `referrer_bonus`, `referred_bonus`, `expiration_days`, `min_redeem_amount`, `membership_uses`, `membership_validity_days`, `gift_card_default_amount`, `tiers_enabled`, `tier_basis`, `card_design`, `locations`, `enrollment_settings`, `terms`, `public_enrollment_enabled`, `apple_wallet_enabled`, `google_wallet_enabled` | | No | See [Fields](#loyalty-programs). |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-programs \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Coffee Club",
    "type": "points",
    "status": "active",
    "currency_code": "USD",
    "welcome_bonus": 50,
    "expiration_days": 365,
    "earn_rules": { "amount_step": 1, "points_per_step": 1 }
  }'
```

#### Response

Returns the created [loyalty program](#loyalty-programs) with `enrollment_url` and `wallet_availability`.

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Coffee Club",
  "description": null,
  "type": "points",
  "status": "active",
  "slug": "coffee-club",
  "currency_code": "USD",
  "earn_rules": {
    "sources": { "orders": true, "invoices": true, "reservations": true, "events": false },
    "amount_step": 1,
    "points_per_step": 1,
    "stamps_per_visit": 1,
    "min_amount": 0,
    "points_per_visit": 0,
    "auto_enroll": false
  },
  "stamps_required": null,
  "cashback_percent": null,
  "welcome_bonus": 50,
  "birthday_bonus": 0,
  "referrals_enabled": false,
  "referrer_bonus": 0,
  "referred_bonus": 0,
  "expiration_days": 365,
  "min_redeem_amount": null,
  "membership_uses": null,
  "membership_validity_days": null,
  "gift_card_default_amount": null,
  "tiers_enabled": false,
  "tier_basis": "lifetime_points",
  "card_design": {
    "background_color": "#111827",
    "foreground_color": "#FFFFFF",
    "label_color": "#9CA3AF",
    "accent_color": "#F59E0B",
    "logo_url": null,
    "icon_url": null,
    "strip_image_url": null,
    "stamp_icon": "star"
  },
  "locations": null,
  "enrollment_settings": null,
  "terms": null,
  "public_enrollment_enabled": true,
  "apple_wallet_enabled": true,
  "google_wallet_enabled": true,
  "google_class_id": null,
  "google_class_synced_at": null,
  "member_count": 0,
  "created_by_user_id": null,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-01T15:00:00.000Z",
  "deleted_at": null,
  "enrollment_url": "https://www.achieveapex.com/l/456/coffee-club",
  "wallet_availability": { "apple": true, "google": true }
}
```

#### Defaults by type

| Type | Default when omitted |
|---|---|
| `stamps` | `stamps_required: 10` |
| `points` | `tier_basis: "lifetime_points"` |
| `cashback` | `cashback_percent: 5` |
| `membership` | `membership_uses: 10` |

`card_design` and `earn_rules` get the default design and rules shown above. Keys you send are merged over them.

#### Errors

All are `400 Bad Request`:

| Message | Cause |
|---|---|
| `This link name is already used by another program` | The `slug` you sent is taken in your organization. Without `slug`, a free one is generated. |
| `A stamp card needs between 2 and 30 stamps` | `stamps_required` out of range. |
| `Cashback must be between 0 and 100 percent` | `cashback_percent` out of range. |
| `Cashback and gift cards need a currency` | `active` cashback or gift card without `currency_code`. |
| `A membership needs at least one use` | `membership_uses` below 1. |
| `Expiration must be at least one day` | `expiration_days` below 1. |
| `Tiers are available for points, stamps and cashback programs` | `tiers_enabled` on a membership or gift card. |
| `Referrals are available for points, stamps and cashback programs` | `referrals_enabled` on a membership or gift card. |
| `card_design.<key> must be a #RRGGBB color` | Invalid color. |
| `earn_rules.<key> must be a positive number` / `earn_rules.amount_step must be greater than zero` | Invalid earning rule. |
| `A card supports up to 10 locations` / `Invalid location latitude` / `Invalid location longitude` | Invalid `locations`. |

<a id="loyalty-programs--update"></a>

### Update a loyalty program

Source: https://www.achieveapex.com/docs/api-reference/loyalty-programs/update

Change a program's settings (partial update), for example to activate, pause or archive it, or to change its earning rules or card design.

#### Endpoint

`PATCH /loyalty-programs/:id`

#### Body parameters

Any field of [Create a loyalty program](#loyalty-programs--create) except `type` and `organization_id`, which cannot be changed. Only the fields you send change. `card_design` and `earn_rules` are merged with the current values, so you can send only the keys you change.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/loyalty-programs/12 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "card_design": { "accent_color": "#10B981" }
  }'
```

#### Response

Returns the updated [loyalty program](#loyalty-programs) (same shape as [Get a loyalty program](#loyalty-programs--get)).

#### Side effects

- Changing `name`, `card_design`, `terms`, `locations`, `status`, `stamps_required` or `currency_code` refreshes every installed Apple Wallet and Google Wallet card of the program in the background.
- Changing `tiers_enabled` or `tier_basis` recalculates every member's tier in the background.
- `archived` programs do not accept new members.

#### Errors

All are `400 Bad Request`:

| Message | Cause |
|---|---|
| `The program type cannot be changed` | `type` differs from the current type. |
| `The organization cannot be changed` | `organization_id` differs from the current organization. |
| `Program not found` | Unknown or deleted program. |

The validation errors of [Create a loyalty program](#loyalty-programs--create) also apply, checked against the program after the change.

<a id="loyalty-programs--delete"></a>

### Delete a loyalty program

Source: https://www.achieveapex.com/docs/api-reference/loyalty-programs/delete

Delete a program that has no members. This is a soft delete: the program gets `deleted_at` and no longer appears in list or get. A program with members cannot be deleted: [archive it](#loyalty-programs--update) with `"status": "archived"` instead.

#### Endpoint

`DELETE /loyalty-programs/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/loyalty-programs/13 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [loyalty program](#loyalty-programs) with `deleted_at` set.

```json
{
  "id": 13,
  "organization_id": 456,
  "name": "Stamp Card",
  "type": "stamps",
  "status": "draft",
  "slug": "stamp-card",
  "member_count": 0,
  "deleted_at": "2026-11-08T10:00:00.000Z",
  "enrollment_url": "https://www.achieveapex.com/l/456/stamp-card",
  "wallet_availability": { "apple": true, "google": true }
}
```

(Shortened: the response contains every field of the program.)

#### Errors

| Status | Message / cause |
|---|---|
| `400 Bad Request` | `This program has members. Archive it instead of deleting it.` |
| `400 Bad Request` | `Program not found` (unknown or already deleted program). |
| `404 Not Found` | A program of another organization. |

---

## Loyalty redemptions

<a id="loyalty-redemptions"></a>

### Loyalty redemptions overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-redemptions

A **redemption** spends part of a card balance and issues a **reward code**. Points and stamps programs redeem a catalog [reward](#loyalty-rewards); cashback and gift cards redeem an amount of money, which becomes a fixed discount. The code is handed over at the counter (mark it `used`) or applied as a discount code at the catalog checkout.

Reward codes are bearer codes: whoever has the code can use it.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/loyalty-redemptions` | [List loyalty redemptions](#loyalty-redemptions--list) |
| `GET` | `/loyalty-redemptions/:id` | [Get a loyalty redemption](#loyalty-redemptions--get) |
| `POST` | `/loyalty-redemptions` | [Redeem a reward](#loyalty-redemptions--create) |
| `PATCH` | `/loyalty-redemptions/:id` | [Use or cancel a redemption](#loyalty-redemptions--update) |

There is no delete: cancel a code instead. The API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body of a redemption.

#### The loyalty redemption object

```json
{
  "id": 801,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "reward_id": 21,
  "transaction_id": 5120,
  "code": "XH4K9PRT",
  "status": "issued",
  "cost": 100,
  "reward_name": "Free coffee",
  "reward_type": "free_item",
  "discount_value": null,
  "expires_at": "2026-12-07T14:00:00.000Z",
  "used_at": null,
  "used_by_user_id": null,
  "channel": "api",
  "order_id": null,
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:00:00.000Z",
  "updated_at": "2026-11-07T14:00:00.000Z",
  "deleted_at": null,
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
  "created_by_user": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Read-only. Organization of the card. |
| `program_id` | integer | Read-only. Program of the card. |
| `member_id` | integer | Read-only. [Card](#loyalty-members) that spent the balance. |
| `contact_id` | integer \| null | Read-only. Contact of the card. |
| `reward_id` | integer \| null | Read-only. Redeemed [reward](#loyalty-rewards). `null` for balance (amount) redemptions. |
| `transaction_id` | integer \| null | Read-only. The [transaction](#loyalty-transactions) that spent the balance. |
| `code` | string | Read-only. Reward code (8 characters). |
| `status` | string | One of `issued`, `used`, `cancelled`, `expired` (see below). Only `used` and `cancelled` can be set. |
| `cost` | number | Read-only. Balance spent. |
| `reward_name` | string \| null | Read-only. Copy of the reward name at the time of the redemption. |
| `reward_type` | string \| null | Read-only. Copy of the reward type. Balance redemptions use `discount_fixed`. |
| `discount_value` | number \| null | Read-only. Copy of the reward discount. Balance redemptions use the amount spent. |
| `expires_at` | string (date-time) \| null | Read-only. When an unused code expires (from the reward `code_validity_days`). |
| `used_at` | string (date-time) \| null | Read-only. When the code was used. |
| `used_by_user_id` | integer \| null | Read-only. User who marked it used (`null` for API keys). |
| `channel` | string \| null | Where it was created: `staff`, `public_page`, `checkout`, `ai_assistant`, `api` or `automation`. |
| `order_id` | integer \| null | Order where the code was used, if any. Can be set when marking it `used`. |
| `metadata` | object \| null | Read-only. Extra data. |
| `created_by_user_id` | integer \| null | Read-only. User who created the redemption (`null` for API keys). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Always `null`. |
| `contact` | object \| null | Read-only, added to every response: `id`, `first_name`, `last_name`, `email`, `phone`. |
| `created_by_user` | object \| null | Read-only, added: `id`, `first_name`, `last_name` of the user who created it. |

##### Status values

| Value | Description |
|-------|-------------|
| `issued` | Code ready to be used |
| `used` | Reward handed over or discount applied |
| `cancelled` | Cancelled; the balance was given back |
| `expired` | Not used before `expires_at`; the balance was given back |

When a redemption is created, the **Loyalty reward redeemed** automation trigger runs.

<a id="loyalty-redemptions--list"></a>

### List loyalty redemptions

Source: https://www.achieveapex.com/docs/api-reference/loyalty-redemptions/list

Retrieve reward codes, or find one by code.

#### Endpoint

`GET /loyalty-redemptions`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | No | ID of your organization. Optional: results are always filtered to the API key's organization. |
| `search` | string | No | Exact reward code, or part of the reward name |
| `member_id` | number | No | Only codes of this card |
| `program_id` | number | No | Only codes of this program |
| `reward_id` | number | No | Only codes of this reward |
| `status` | string | No | `issued`, `used`, `cancelled` or `expired` |
| `channel` | string | No | `staff`, `public_page`, `checkout`, `ai_assistant`, `api` or `automation` |
| `$limit` | number | No | Number of codes to return (default: 10, max: 50) |
| `$skip` | number | No | Number of codes to skip (for pagination) |
| `$sort` | object | No | Sort criteria, e.g. `$sort[created_at]=-1` |

#### Request

```bash
curl -G https://integrations.achieveapex.com/loyalty-redemptions \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'search=XH4K9PRT'
```

```bash
curl -G https://integrations.achieveapex.com/loyalty-redemptions \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'member_id=3001' \
  --data-urlencode 'status=issued' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$sort[created_at]=-1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 801,
      "organization_id": 456,
      "program_id": 12,
      "member_id": 3001,
      "contact_id": 9001,
      "reward_id": 21,
      "transaction_id": 5120,
      "code": "XH4K9PRT",
      "status": "issued",
      "cost": 100,
      "reward_name": "Free coffee",
      "reward_type": "free_item",
      "discount_value": null,
      "expires_at": "2026-12-07T14:00:00.000Z",
      "used_at": null,
      "used_by_user_id": null,
      "channel": "api",
      "order_id": null,
      "metadata": null,
      "created_by_user_id": null,
      "created_at": "2026-11-07T14:00:00.000Z",
      "updated_at": "2026-11-07T14:00:00.000Z",
      "deleted_at": null,
      "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
      "created_by_user": null
    }
  ]
}
```

To resolve a code scanned at the counter together with its card, you can also use the [`scan`](#loyalty-actions--scan) action. To retrieve one redemption, see [Get a loyalty redemption](#loyalty-redemptions--get).

<a id="loyalty-redemptions--get"></a>

### Get a loyalty redemption

Source: https://www.achieveapex.com/docs/api-reference/loyalty-redemptions/get

Retrieve one redemption (reward code) by ID.

#### Endpoint

`GET /loyalty-redemptions/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/loyalty-redemptions/801 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 801,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "reward_id": 21,
  "transaction_id": 5120,
  "code": "XH4K9PRT",
  "status": "issued",
  "cost": 100,
  "reward_name": "Free coffee",
  "reward_type": "free_item",
  "discount_value": null,
  "expires_at": "2026-12-07T14:00:00.000Z",
  "used_at": null,
  "used_by_user_id": null,
  "channel": "api",
  "order_id": null,
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:00:00.000Z",
  "updated_at": "2026-11-07T14:00:00.000Z",
  "deleted_at": null,
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
  "created_by_user": null
}
```

To find a code typed or scanned at the counter, use [`search`](#loyalty-redemptions--list) or the [`scan`](#loyalty-actions--scan) action.

<a id="loyalty-redemptions--create"></a>

### Redeem a reward

Source: https://www.achieveapex.com/docs/api-reference/loyalty-redemptions/create

Spend a card balance and issue a reward code. Send `reward_id` to redeem a catalog reward (points and stamps programs), or `amount` to spend money from a cashback or gift card balance.

#### Endpoint

`POST /loyalty-redemptions`

#### Request

##### Redeem a catalog reward

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-redemptions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "member_id": 3001,
    "reward_id": 21,
    "mark_used": true
  }'
```

##### Spend a cashback or gift card balance

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-redemptions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "member_id": 3003,
    "amount": 15
  }'
```

#### Response

```json
{
  "id": 801,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "reward_id": 21,
  "transaction_id": 5120,
  "code": "XH4K9PRT",
  "status": "used",
  "cost": 100,
  "reward_name": "Free coffee",
  "reward_type": "free_item",
  "discount_value": null,
  "expires_at": "2026-12-07T14:00:00.000Z",
  "used_at": "2026-11-07T14:00:00.000Z",
  "used_by_user_id": null,
  "channel": "api",
  "order_id": null,
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:00:00.000Z",
  "updated_at": "2026-11-07T14:00:00.000Z",
  "deleted_at": null,
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
  "created_by_user": null
}
```

Returns the [redemption](#loyalty-redemptions). Without `mark_used`, `status` is `issued`: give the `code` to the customer and [mark it used](#loyalty-redemptions--update) when the reward is handed over.

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `member_id` | Number | Yes | ID of the card |
| `reward_id` | Number | One of `reward_id` / `amount` | Reward of the card's program ([Loyalty Rewards](#loyalty-rewards)) |
| `amount` | Number | One of `reward_id` / `amount` | Cashback and gift cards: amount to spend, in the program currency |
| `mark_used` | Boolean | No | `true` marks the code as used at once (reward handed over at the counter) |
| `channel` | String | No | Defaults to `api` for API key requests |

#### Business rules

The request returns `400 Bad Request` with one of these messages when a rule is not met:

| Message | Cause |
|---------|-------|
| `Not enough balance for this reward` | The card balance is below the reward `cost` |
| `Not enough balance` | The card balance is below `amount` |
| `This reward requires the Gold tier` | The reward has a minimum tier the member has not reached (the tier name varies) |
| `This reward is out of stock` | The reward `stock` is used up |
| `This reward is not available` | The reward is `inactive` |
| `The minimum to redeem is 10` | Cashback: `amount` is below the program `min_redeem_amount` |
| `Only cashback and gift card balances can be spent by amount` | `amount` was sent for a points, stamps or membership card |
| `This card is blocked` / `This card has expired` | The card cannot be used |
| `This program is not active` | The program is draft, paused or archived |
| `reward_id or amount is required` | Neither was sent |

`Reward not found` (404) is returned when the reward does not belong to the card's program.

<a id="loyalty-redemptions--update"></a>

### Use or cancel a redemption

Source: https://www.achieveapex.com/docs/api-reference/loyalty-redemptions/update

Mark a reward code as used when the reward is handed over, or cancel it to give the balance back to the card.

#### Endpoint

`PATCH /loyalty-redemptions/:id`

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/loyalty-redemptions/801 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "used"
  }'
```

```bash
curl -X PATCH https://integrations.achieveapex.com/loyalty-redemptions/801 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled"
  }'
```

#### Response

```json
{
  "id": 801,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "reward_id": 21,
  "transaction_id": 5120,
  "code": "XH4K9PRT",
  "status": "used",
  "cost": 100,
  "reward_name": "Free coffee",
  "reward_type": "free_item",
  "discount_value": null,
  "expires_at": "2026-12-07T14:00:00.000Z",
  "used_at": "2026-11-07T15:30:00.000Z",
  "used_by_user_id": null,
  "channel": "api",
  "order_id": null,
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:00:00.000Z",
  "updated_at": "2026-11-07T15:30:00.000Z",
  "deleted_at": null,
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
  "created_by_user": null
}
```

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | String | Yes | `used` or `cancelled` |
| `order_id` | Number | No | With `used`: ID of the order where the code was applied |

#### Behavior

- **`used`** only works on an `issued` code that has not expired. Marking an already used code as used again returns it unchanged. The update is atomic, so the same code cannot be used twice.
- **`cancelled`** is meant for `issued` codes: it gives the `cost` back to the card balance (a `reversal` [transaction](#loyalty-transactions)) and returns the reward stock. Cancelling an already cancelled code returns it unchanged.
- Other fields cannot be changed.

#### Errors

| Message | Cause |
|---------|-------|
| `This code has expired` | `used` on a code past its `expires_at` |
| `This code is cancelled` / `This code is expired` | `used` on a code that is not `issued` |
| `This code was already used` | Another request used it at the same time |
| `A used code cannot be cancelled` | `cancelled` on a used code |
| `Only status used or cancelled can be set` | Any other `status` |
| `Redemption not found` (404) | Unknown ID |

---

## Loyalty reports

<a id="loyalty-reports"></a>

### Loyalty reports overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-reports

Get the key figures of your loyalty programs: members, balance earned and redeemed, reward codes, outstanding balance, daily series and top members. This resource only has one read-only operation.

#### Endpoint

`GET /loyalty-reports`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | Yes | ID of your organization (the API key's organization). Without it the request returns `400` `organization_id is required`. |
| `program_id` | number | No | Only this program. Without it, all programs are combined |
| `days` | number | No | Period in days, from 1 to 365 (default: 30) |

#### Request

```bash
curl -G https://integrations.achieveapex.com/loyalty-reports \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'program_id=12' \
  --data-urlencode 'days=30'
```

#### Response

```json
{
  "days": 30,
  "program_id": 12,
  "members": {
    "total": 128,
    "active": 126,
    "new_members": 40,
    "engaged": 75,
    "repeat_members": 61,
    "wallet_members": 52,
    "repeat_rate": 47.7,
    "wallet_rate": 40.6
  },
  "movements": {
    "earned": 9850,
    "redeemed": 4200,
    "expired": 0,
    "purchases": 310,
    "member_revenue": 8120.5
  },
  "redemptions": {
    "total": 42,
    "used": 35,
    "pending": 5
  },
  "programs": [
    {
      "id": 12,
      "name": "Coffee Club",
      "type": "points",
      "status": "active",
      "currency_code": "USD",
      "members": 128,
      "outstanding_balance": 15430
    }
  ],
  "series": [
    { "day": "2026-11-06", "earned": 410, "redeemed": 200, "purchases": 14 }
  ],
  "enrollment_series": [
    { "day": "2026-11-06", "members": 3 }
  ],
  "enrollment_sources": [
    { "enrollment_source": "api", "members": 22 },
    { "enrollment_source": "public_page", "members": 18 }
  ],
  "top_members": [
    {
      "id": 3001,
      "program_id": 12,
      "member_code": "K7PX2M9QRT",
      "balance": 230,
      "lifetime_earned": 480,
      "visits_count": 14,
      "lifetime_spend": 430.5,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    }
  ]
}
```

#### Response fields

| Field | Description |
|---|---|
| `members.total` / `members.active` | All members and members with `active` status |
| `members.new_members` | Members enrolled in the period |
| `members.engaged` | Members with activity in the period |
| `members.repeat_members` / `members.repeat_rate` | Members with 2 or more visits, and their percentage |
| `members.wallet_members` / `members.wallet_rate` | Members who added the card to Apple Wallet or Google Wallet, and their percentage |
| `movements.earned` | Balance earned in the period (purchases, bonuses and referrals) |
| `movements.redeemed` | Balance redeemed or used in the period |
| `movements.expired` | Balance expired in the period |
| `movements.purchases` / `movements.member_revenue` | Purchases registered on cards in the period and their total amount |
| `redemptions` | Reward codes created in the period: total, used and still pending (`issued`) |
| `programs[].outstanding_balance` | Balance currently held by members (for cashback and gift cards, the money you owe) |
| `series` | Earned, redeemed and purchases per day |
| `enrollment_series` | New members per day |
| `enrollment_sources` | New members in the period by `enrollment_source` |
| `top_members` | The 10 members with the highest `lifetime_earned` |

Balances mix units when several programs of different types are combined; filter by `program_id` for exact figures.

---

## Loyalty rewards

<a id="loyalty-rewards"></a>

### Loyalty rewards overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-rewards

The reward catalog of a loyalty program.

A **reward** is what members of a points or stamps program can get with their balance: a free item, a fixed or percentage discount, or a custom benefit. List rewards to show what a customer can redeem and to get the `reward_id` for a [redemption](#loyalty-redemptions--create). Rewards can be managed in the Loyalty app or through this API.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/loyalty-rewards` | [List loyalty rewards](#loyalty-rewards--list) |
| `GET` | `/loyalty-rewards/:id` | [Get a loyalty reward](#loyalty-rewards--get) |
| `POST` | `/loyalty-rewards` | [Create a loyalty reward](#loyalty-rewards--create) |
| `PATCH` | `/loyalty-rewards/:id` | [Update a loyalty reward](#loyalty-rewards--update) |
| `DELETE` | `/loyalty-rewards/:id` | [Delete a loyalty reward](#loyalty-rewards--delete) |

The API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body on create.

#### The loyalty reward object

```json
{
  "id": 21,
  "organization_id": 456,
  "program_id": 12,
  "name": "Free coffee",
  "description": "Any size",
  "image_url": null,
  "cost": 100,
  "reward_type": "free_item",
  "discount_value": null,
  "product_id": null,
  "min_tier_id": null,
  "stock": null,
  "code_validity_days": 30,
  "status": "active",
  "sort_order": 0,
  "redeemed_count": 37,
  "created_at": "2026-11-01T15:10:00.000Z",
  "updated_at": "2026-11-01T15:10:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization of the program. Required on create (must be the program's organization); cannot be changed. |
| `program_id` | integer | [Loyalty program](#loyalty-programs) of the reward. Required on create; cannot be changed. |
| `name` | string | Reward name (1 to 160 characters). Required on create. |
| `description` | string \| null | Description (up to 2000 characters). |
| `image_url` | string \| null | Image URL (up to 2048 characters). |
| `cost` | number | Balance needed (points or stamps), greater than 0. Required on create. |
| `reward_type` | string | One of `free_item`, `discount_fixed`, `discount_percent`, `custom`. Default `custom`. |
| `discount_value` | number \| null | Discount amount (`discount_fixed`) or percentage up to 100 (`discount_percent`). Required and greater than 0 for discount types. |
| `product_id` | integer \| null | Related [product](#products), if any. |
| `min_tier_id` | integer \| null | Minimum [tier](#loyalty-tiers) required to redeem it. Must be a tier of the same program. |
| `stock` | integer \| null | Units available in total, `0` or more. `null` = unlimited. |
| `code_validity_days` | integer \| null | Days the reward code stays valid after redeeming (at least 1). `null` = no expiry. |
| `status` | string | One of `active`, `inactive`. Default `active`. Only active rewards can be redeemed. |
| `sort_order` | integer | Display order. Default `0`. |
| `redeemed_count` | integer | Read-only. Units already redeemed (counted against `stock`). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the reward is deleted. |

#### Related

- [Loyalty redemptions](#loyalty-redemptions)
- [Loyalty programs](#loyalty-programs)
- [Loyalty tiers](#loyalty-tiers)

<a id="loyalty-rewards--list"></a>

### List loyalty rewards

Source: https://www.achieveapex.com/docs/api-reference/loyalty-rewards/list

Retrieve the rewards of a loyalty program.

#### Endpoint

`GET /loyalty-rewards`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | No | ID of your organization. Optional: results are always filtered to the API key's organization. |
| `program_id` | number | No | Only rewards of this program |
| `status` | string | No | `active` or `inactive` |
| `reward_type` | string | No | `free_item`, `discount_fixed`, `discount_percent` or `custom` |
| `$limit` | number | No | Number of rewards to return (default: 10, max: 50) |
| `$skip` | number | No | Number of rewards to skip (for pagination) |
| `$sort` | object | No | Sort criteria, e.g. `$sort[cost]=1` or `$sort[sort_order]=1` |

#### Request

```bash
curl -G https://integrations.achieveapex.com/loyalty-rewards \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'program_id=12' \
  --data-urlencode 'status=active' \
  --data-urlencode '$sort[cost]=1'
```

#### Response

```json
{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 21,
      "organization_id": 456,
      "program_id": 12,
      "name": "Free coffee",
      "description": "Any size",
      "image_url": null,
      "cost": 100,
      "reward_type": "free_item",
      "discount_value": null,
      "product_id": null,
      "min_tier_id": null,
      "stock": null,
      "code_validity_days": 30,
      "status": "active",
      "sort_order": 0,
      "redeemed_count": 37,
      "created_at": "2026-11-01T15:10:00.000Z",
      "updated_at": "2026-11-01T15:10:00.000Z",
      "deleted_at": null
    },
    {
      "id": 22,
      "organization_id": 456,
      "program_id": 12,
      "name": "10% off",
      "description": null,
      "image_url": null,
      "cost": 300,
      "reward_type": "discount_percent",
      "discount_value": 10,
      "product_id": null,
      "min_tier_id": 4,
      "stock": 100,
      "code_validity_days": 15,
      "status": "active",
      "sort_order": 1,
      "redeemed_count": 12,
      "created_at": "2026-11-01T15:12:00.000Z",
      "updated_at": "2026-11-01T15:12:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="loyalty-rewards--get"></a>

### Get a loyalty reward

Source: https://www.achieveapex.com/docs/api-reference/loyalty-rewards/get

Retrieve a single reward by ID.

#### Endpoint

`GET /loyalty-rewards/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/loyalty-rewards/21 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 21,
  "organization_id": 456,
  "program_id": 12,
  "name": "Free coffee",
  "description": "Any size",
  "image_url": null,
  "cost": 100,
  "reward_type": "free_item",
  "discount_value": null,
  "product_id": null,
  "min_tier_id": null,
  "stock": null,
  "code_validity_days": 30,
  "status": "active",
  "sort_order": 0,
  "redeemed_count": 37,
  "created_at": "2026-11-01T15:10:00.000Z",
  "updated_at": "2026-11-01T15:10:00.000Z",
  "deleted_at": null
}
```

<a id="loyalty-rewards--create"></a>

### Create a loyalty reward

Source: https://www.achieveapex.com/docs/api-reference/loyalty-rewards/create

Add a reward to a program's catalog.

#### Endpoint

`POST /loyalty-rewards`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. Must be the program's organization. |
| `program_id` | integer | Yes | ID of the [loyalty program](#loyalty-programs). |
| `name` | string | Yes | Reward name (1 to 160 characters). |
| `cost` | number | Yes | Balance needed, greater than 0. |
| `reward_type` | string | No | `free_item`, `discount_fixed`, `discount_percent` or `custom` (default). |
| `discount_value` | number | For discount types | Amount (`discount_fixed`) or percentage up to 100 (`discount_percent`). |
| `description` | string \| null | No | Description. |
| `image_url` | string \| null | No | Image URL. |
| `product_id` | integer \| null | No | Related product. |
| `min_tier_id` | integer \| null | No | Minimum tier, from the same program. |
| `stock` | integer \| null | No | Total units available. `null` = unlimited. |
| `code_validity_days` | integer \| null | No | Days a reward code stays valid. `null` = no expiry. |
| `status` | string | No | `active` (default) or `inactive`. |
| `sort_order` | integer | No | Display order. Default `0`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-rewards \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "program_id": 12,
    "name": "Free coffee",
    "description": "Any size",
    "cost": 100,
    "reward_type": "free_item",
    "code_validity_days": 30
  }'
```

#### Response

```json
{
  "id": 21,
  "organization_id": 456,
  "program_id": 12,
  "name": "Free coffee",
  "description": "Any size",
  "image_url": null,
  "cost": 100,
  "reward_type": "free_item",
  "discount_value": null,
  "product_id": null,
  "min_tier_id": null,
  "stock": null,
  "code_validity_days": 30,
  "status": "active",
  "sort_order": 0,
  "redeemed_count": 0,
  "created_at": "2026-11-01T15:10:00.000Z",
  "updated_at": "2026-11-01T15:10:00.000Z",
  "deleted_at": null
}
```

#### Errors

All are `400 Bad Request`:

| Message | Cause |
|---|---|
| `Program not found in this organization` | `program_id` is not a program of `organization_id`. |
| `A discount reward needs a discount value` | `discount_fixed` / `discount_percent` without a positive `discount_value`. |
| `A percentage discount cannot exceed 100` | `discount_percent` with `discount_value` above 100. |
| `The minimum tier must belong to the same program` | `min_tier_id` is not a tier of the program. |

<a id="loyalty-rewards--update"></a>

### Update a loyalty reward

Source: https://www.achieveapex.com/docs/api-reference/loyalty-rewards/update

Change a reward (partial update), for example its cost, stock or status.

#### Endpoint

`PATCH /loyalty-rewards/:id`

#### Body parameters

Any field of [Create a loyalty reward](#loyalty-rewards--create) except `program_id` and `organization_id`, which cannot be changed. Only the fields you send change. The rules for `discount_value` and `min_tier_id` are checked against the reward after the change.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/loyalty-rewards/21 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cost": 120,
    "stock": 50
  }'
```

#### Response

Returns the updated [reward](#loyalty-rewards).

Reward codes already issued keep the name, type, discount and cost they were redeemed with.

#### Errors

| Status | Message / cause |
|---|---|
| `400 Bad Request` | `The program cannot be changed` |
| `400 Bad Request` | `Record not found` (unknown or deleted reward). |
| `400 Bad Request` | Same validation messages as [Create a loyalty reward](#loyalty-rewards--create). |

<a id="loyalty-rewards--delete"></a>

### Delete a loyalty reward

Source: https://www.achieveapex.com/docs/api-reference/loyalty-rewards/delete

Delete a reward from the catalog. This is a soft delete: the reward gets `deleted_at` and no longer appears in list or get. To hide it temporarily, set `"status": "inactive"` instead.

#### Endpoint

`DELETE /loyalty-rewards/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/loyalty-rewards/21 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [reward](#loyalty-rewards) with `deleted_at` set.

```json
{
  "id": 21,
  "organization_id": 456,
  "program_id": 12,
  "name": "Free coffee",
  "description": "Any size",
  "image_url": null,
  "cost": 100,
  "reward_type": "free_item",
  "discount_value": null,
  "product_id": null,
  "min_tier_id": null,
  "stock": null,
  "code_validity_days": 30,
  "status": "active",
  "sort_order": 0,
  "redeemed_count": 37,
  "created_at": "2026-11-01T15:10:00.000Z",
  "updated_at": "2026-11-01T15:10:00.000Z",
  "deleted_at": "2026-11-08T10:00:00.000Z"
}
```

Reward codes already issued for this reward are not cancelled.

---

## Loyalty tiers

<a id="loyalty-tiers"></a>

### Loyalty tiers overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-tiers

Tiers (levels such as Silver, Gold, Platinum) of a loyalty program.

Programs with `tiers_enabled` place each member in a **tier** according to the program `tier_basis`: lifetime points earned (`lifetime_points`), lifetime spend (`lifetime_spend`) or number of visits (`visits`). A member is in the highest tier whose `threshold` they reached. The tier is recalculated after every balance movement and shown on the member as `tier_id` / `tier`.

A tier `earn_multiplier` multiplies the points or cashback earned per purchase (not stamps). Rewards can require a minimum tier (`min_tier_id`).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/loyalty-tiers` | [List loyalty tiers](#loyalty-tiers--list) |
| `GET` | `/loyalty-tiers/:id` | [Get a loyalty tier](#loyalty-tiers--get) |
| `POST` | `/loyalty-tiers` | [Create a loyalty tier](#loyalty-tiers--create) |
| `PATCH` | `/loyalty-tiers/:id` | [Update a loyalty tier](#loyalty-tiers--update) |
| `DELETE` | `/loyalty-tiers/:id` | [Delete a loyalty tier](#loyalty-tiers--delete) |

The API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body on create.

#### The loyalty tier object

```json
{
  "id": 4,
  "organization_id": 456,
  "program_id": 12,
  "name": "Gold",
  "threshold": 500,
  "earn_multiplier": 1.5,
  "benefits": "1.5x points and early access to new products",
  "color": "#F59E0B",
  "sort_order": 1,
  "created_at": "2026-11-01T15:05:00.000Z",
  "updated_at": "2026-11-01T15:05:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization of the program. Required on create (must be the program's organization); cannot be changed. |
| `program_id` | integer | [Loyalty program](#loyalty-programs) of the tier. Required on create; cannot be changed. |
| `name` | string | Tier name (1 to 120 characters). Required on create. |
| `threshold` | number | Value of the program `tier_basis` needed to reach the tier, `0` or more. Default `0`. |
| `earn_multiplier` | number | Multiplier applied to points and cashback earned, `0` to `100`. Default `1`. |
| `benefits` | string \| null | Text describing the tier benefits (up to 2000 characters). |
| `color` | string \| null | Tier color shown on the card, for example `#F59E0B` (up to 16 characters). |
| `sort_order` | integer | Display order. Default `0`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the tier is deleted. |

#### Related

- [Loyalty programs](#loyalty-programs)
- [Loyalty rewards](#loyalty-rewards)
- [Loyalty members](#loyalty-members)

<a id="loyalty-tiers--list"></a>

### List loyalty tiers

Source: https://www.achieveapex.com/docs/api-reference/loyalty-tiers/list

Retrieve the tiers of a loyalty program.

#### Endpoint

`GET /loyalty-tiers`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | No | ID of your organization. Optional: results are always filtered to the API key's organization. |
| `program_id` | number | No | Only tiers of this program |
| `$limit` | number | No | Number of tiers to return (default: 10, max: 50) |
| `$skip` | number | No | Number of tiers to skip (for pagination) |
| `$sort` | object | No | Sort criteria, e.g. `$sort[threshold]=1` |

#### Request

```bash
curl -G https://integrations.achieveapex.com/loyalty-tiers \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'program_id=12' \
  --data-urlencode '$sort[threshold]=1'
```

#### Response

```json
{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 3,
      "organization_id": 456,
      "program_id": 12,
      "name": "Silver",
      "threshold": 0,
      "earn_multiplier": 1,
      "benefits": null,
      "color": "#9CA3AF",
      "sort_order": 0,
      "created_at": "2026-11-01T15:04:00.000Z",
      "updated_at": "2026-11-01T15:04:00.000Z",
      "deleted_at": null
    },
    {
      "id": 4,
      "organization_id": 456,
      "program_id": 12,
      "name": "Gold",
      "threshold": 500,
      "earn_multiplier": 1.5,
      "benefits": "1.5x points and early access to new products",
      "color": "#F59E0B",
      "sort_order": 1,
      "created_at": "2026-11-01T15:05:00.000Z",
      "updated_at": "2026-11-01T15:05:00.000Z",
      "deleted_at": null
    }
  ]
}
```

To retrieve one tier, see [Get a loyalty tier](#loyalty-tiers--get).

<a id="loyalty-tiers--get"></a>

### Get a loyalty tier

Source: https://www.achieveapex.com/docs/api-reference/loyalty-tiers/get

Retrieve one tier by ID.

#### Endpoint

`GET /loyalty-tiers/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/loyalty-tiers/4 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 4,
  "organization_id": 456,
  "program_id": 12,
  "name": "Gold",
  "threshold": 500,
  "earn_multiplier": 1.5,
  "benefits": "1.5x points and early access to new products",
  "color": "#F59E0B",
  "sort_order": 1,
  "created_at": "2026-11-01T15:05:00.000Z",
  "updated_at": "2026-11-01T15:05:00.000Z",
  "deleted_at": null
}
```

<a id="loyalty-tiers--create"></a>

### Create a loyalty tier

Source: https://www.achieveapex.com/docs/api-reference/loyalty-tiers/create

Add a tier to a loyalty program. Tiers only affect members when the program has `tiers_enabled: true` (points, stamps and cashback programs).

#### Endpoint

`POST /loyalty-tiers`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. Must be the program's organization. |
| `program_id` | integer | Yes | ID of the [loyalty program](#loyalty-programs). |
| `name` | string | Yes | Tier name (1 to 120 characters). |
| `threshold` | number | No | Value of the program `tier_basis` needed to reach the tier. Default `0`. |
| `earn_multiplier` | number | No | `0` to `100`. Default `1`. |
| `benefits` | string \| null | No | Text describing the benefits. |
| `color` | string \| null | No | Color, for example `#F59E0B`. |
| `sort_order` | integer | No | Display order. Default `0`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-tiers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "program_id": 12,
    "name": "Gold",
    "threshold": 500,
    "earn_multiplier": 1.5,
    "benefits": "1.5x points and early access to new products",
    "color": "#F59E0B",
    "sort_order": 1
  }'
```

#### Response

```json
{
  "id": 4,
  "organization_id": 456,
  "program_id": 12,
  "name": "Gold",
  "threshold": 500,
  "earn_multiplier": 1.5,
  "benefits": "1.5x points and early access to new products",
  "color": "#F59E0B",
  "sort_order": 1,
  "created_at": "2026-11-01T15:05:00.000Z",
  "updated_at": "2026-11-01T15:05:00.000Z",
  "deleted_at": null
}
```

After the tier is created, every member of the program is re-evaluated in the background, so members who already reached the threshold move to the new tier.

#### Errors

| Status | Message / cause |
|---|---|
| `400 Bad Request` | `Program not found in this organization` |
| `400 Bad Request` | Schema validation failed (missing `name`, `threshold` below 0, `earn_multiplier` above 100, unknown field). |

<a id="loyalty-tiers--update"></a>

### Update a loyalty tier

Source: https://www.achieveapex.com/docs/api-reference/loyalty-tiers/update

Change a tier's name, threshold, multiplier, benefits, color or order (partial update).

#### Endpoint

`PATCH /loyalty-tiers/:id`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Tier name. |
| `threshold` | number | No | Value needed to reach the tier. |
| `earn_multiplier` | number | No | `0` to `100`. |
| `benefits` | string \| null | No | Benefits text. |
| `color` | string \| null | No | Color. |
| `sort_order` | integer | No | Display order. |

`program_id` and `organization_id` cannot be changed.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/loyalty-tiers/4 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 400,
    "earn_multiplier": 2
  }'
```

#### Response

Returns the updated [tier](#loyalty-tiers). Every member of the program is re-evaluated in the background.

#### Errors

| Status | Message / cause |
|---|---|
| `400 Bad Request` | `The program cannot be changed` |
| `400 Bad Request` | `Record not found` (unknown or deleted tier). |

<a id="loyalty-tiers--delete"></a>

### Delete a loyalty tier

Source: https://www.achieveapex.com/docs/api-reference/loyalty-tiers/delete

Delete a tier. This is a soft delete: the tier gets `deleted_at` and no longer appears in list or get. Members of the program are re-evaluated in the background.

#### Endpoint

`DELETE /loyalty-tiers/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/loyalty-tiers/4 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [tier](#loyalty-tiers) with `deleted_at` set.

```json
{
  "id": 4,
  "organization_id": 456,
  "program_id": 12,
  "name": "Gold",
  "threshold": 500,
  "earn_multiplier": 1.5,
  "benefits": "1.5x points and early access to new products",
  "color": "#F59E0B",
  "sort_order": 1,
  "created_at": "2026-11-01T15:05:00.000Z",
  "updated_at": "2026-11-01T15:05:00.000Z",
  "deleted_at": "2026-11-08T10:00:00.000Z"
}
```

Rewards that use this tier as `min_tier_id` are not changed automatically: update them to another tier or `null`.

---

## Loyalty transactions

<a id="loyalty-transactions"></a>

### Loyalty transactions overview

Source: https://www.achieveapex.com/docs/api-reference/loyalty-transactions

Every change to a card balance is a **transaction**: purchases, bonuses, redemptions, check-ins, top-ups, expirations and manual adjustments. The ledger is append-only: transactions cannot be edited or deleted. To undo a movement, create an opposite adjustment.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/loyalty-transactions` | [List loyalty transactions](#loyalty-transactions--list) |
| `GET` | `/loyalty-transactions/:id` | [Get a loyalty transaction](#loyalty-transactions--get) |
| `POST` | `/loyalty-transactions` | [Adjust a balance](#loyalty-transactions--create) |

There is no update or delete. The API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body of an adjustment.

#### The loyalty transaction object

```json
{
  "id": 5121,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "type": "earn",
  "amount": 25,
  "balance_after": 255,
  "remaining_amount": 25,
  "expires_at": "2027-11-07T14:05:00.000Z",
  "expired_at": null,
  "source_type": "pos",
  "source_id": "POS-TICKET-10045",
  "source_amount": 25.5,
  "description": "In-store purchase",
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:05:00.000Z",
  "updated_at": "2026-11-07T14:05:00.000Z",
  "deleted_at": null,
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "5551234567"
  },
  "created_by_user": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Read-only. Organization of the card. |
| `program_id` | integer | Read-only. Program of the card. |
| `member_id` | integer | Read-only. [Card](#loyalty-members) whose balance moved. |
| `contact_id` | integer \| null | Read-only. Contact of the card. |
| `type` | string | Read-only. Kind of movement (see [Transaction types](#transaction-types)). |
| `amount` | number | Read-only. Signed amount: positive adds balance, negative removes it. |
| `balance_after` | number | Read-only. Card balance right after this movement. |
| `remaining_amount` | number \| null | Read-only. For credits that can expire: the part not spent yet. Spending uses the credits that expire first. |
| `expires_at` | string (date-time) \| null | Read-only. When the remaining part of this credit expires. |
| `expired_at` | string (date-time) \| null | Read-only. When the remaining part of this credit expired. |
| `source_type` | string \| null | Read-only. Origin of the movement, e.g. `pos` (a purchase registered with a `reference`), `order`, `invoice`, `reservation`, `event_registration`, `reward`, `check_in`, `manual`, `api`. |
| `source_id` | string \| null | Read-only. ID of the origin (your `reference`, an order ID, a reward ID...). |
| `source_amount` | number \| null | Read-only. Purchase amount that produced an `earn` movement. |
| `description` | string \| null | Text shown in the history (up to 500 characters). |
| `metadata` | object \| null | Read-only. Extra data of the movement. |
| `idempotency_key` | string \| null | Write-only. Your unique key for an [adjustment](#loyalty-transactions--create). Never returned. |
| `created_by_user_id` | integer \| null | Read-only. User who made the movement (`null` for API key movements). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Always `null`: transactions are never deleted. |
| `contact` | object \| null | Read-only, added to every response: `id`, `first_name`, `last_name`, `email`, `phone`. |
| `created_by_user` | object \| null | Read-only, added: `id`, `first_name`, `last_name` of the user who made the movement. |

##### Transaction types

| Value | Description |
|-------|-------------|
| `earn` | Earned from a purchase or visit |
| `bonus` | Welcome or birthday bonus |
| `referral` | Referral bonus |
| `redeem` | Spent on a reward or cashback |
| `use` | Membership check-in or gift card spend |
| `load` | Gift card or membership uses loaded |
| `adjust` | Manual adjustment |
| `expire` | Expired balance |
| `reversal` | Returned balance (cancelled purchase or cancelled reward code) |

<a id="loyalty-transactions--list"></a>

### List loyalty transactions

Source: https://www.achieveapex.com/docs/api-reference/loyalty-transactions/list

Retrieve the balance history of a card or of your whole organization.

#### Endpoint

`GET /loyalty-transactions`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | number | No | ID of your organization. Optional: results are always filtered to the API key's organization. |
| `member_id` | number | No | Only movements of this card |
| `program_id` | number | No | Only movements of this program |
| `contact_id` | number | No | Only movements of this contact |
| `type` | string | No | Filter by type, e.g. `earn` or `redeem`. Several types: `type[$in][]=earn&type[$in][]=bonus` |
| `source_type` / `source_id` | string | No | Find the movement of one source, e.g. `source_type=pos&source_id=POS-TICKET-10045` |
| `created_at` | object | No | Date range, e.g. `created_at[$gte]=2026-11-01T00:00:00.000Z` |
| `$limit` | number | No | Number of movements to return (default: 10, max: 50) |
| `$skip` | number | No | Number of movements to skip (for pagination) |
| `$sort` | object | No | Sort criteria, e.g. `$sort[created_at]=-1` for newest first |

#### Request

```bash
curl -G https://integrations.achieveapex.com/loyalty-transactions \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'member_id=3001' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$skip=0' \
  --data-urlencode '$sort[created_at]=-1'
```

#### Response

```json
{
  "total": 2,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 5121,
      "organization_id": 456,
      "program_id": 12,
      "member_id": 3001,
      "contact_id": 9001,
      "type": "earn",
      "amount": 25,
      "balance_after": 255,
      "remaining_amount": 25,
      "expires_at": "2027-11-07T14:05:00.000Z",
      "expired_at": null,
      "source_type": "pos",
      "source_id": "POS-TICKET-10045",
      "source_amount": 25.5,
      "description": "In-store purchase",
      "metadata": null,
      "created_by_user_id": null,
      "created_at": "2026-11-07T14:05:00.000Z",
      "updated_at": "2026-11-07T14:05:00.000Z",
      "deleted_at": null,
      "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
      "created_by_user": null
    },
    {
      "id": 5120,
      "organization_id": 456,
      "program_id": 12,
      "member_id": 3001,
      "contact_id": 9001,
      "type": "redeem",
      "amount": -100,
      "balance_after": 230,
      "remaining_amount": null,
      "expires_at": null,
      "expired_at": null,
      "source_type": "reward",
      "source_id": "21",
      "source_amount": null,
      "description": "Redeemed: Free coffee",
      "metadata": null,
      "created_by_user_id": null,
      "created_at": "2026-11-07T14:00:00.000Z",
      "updated_at": "2026-11-07T14:00:00.000Z",
      "deleted_at": null,
      "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
      "created_by_user": null
    }
  ]
}
```

To retrieve one movement, see [Get a loyalty transaction](#loyalty-transactions--get).

<a id="loyalty-transactions--get"></a>

### Get a loyalty transaction

Source: https://www.achieveapex.com/docs/api-reference/loyalty-transactions/get

Retrieve one balance movement by ID.

#### Endpoint

`GET /loyalty-transactions/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/loyalty-transactions/5121 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 5121,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "type": "earn",
  "amount": 25,
  "balance_after": 255,
  "remaining_amount": 25,
  "expires_at": "2027-11-07T14:05:00.000Z",
  "expired_at": null,
  "source_type": "pos",
  "source_id": "POS-TICKET-10045",
  "source_amount": 25.5,
  "description": "In-store purchase",
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:05:00.000Z",
  "updated_at": "2026-11-07T14:05:00.000Z",
  "deleted_at": null,
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
  "created_by_user": null
}
```

<a id="loyalty-transactions--create"></a>

### Adjust a balance

Source: https://www.achieveapex.com/docs/api-reference/loyalty-transactions/create

Add or remove balance on a card manually, for example to fix a mistake or grant a goodwill bonus. To register a purchase with the program earning rules, use [Register a Purchase](#loyalty-actions--register-purchase) instead.

#### Endpoint

`POST /loyalty-transactions`

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/loyalty-transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "member_id": 3001,
    "amount": -20,
    "description": "Correction: duplicated ticket 10044",
    "idempotency_key": "fix-10044"
  }'
```

#### Response

```json
{
  "id": 5124,
  "organization_id": 456,
  "program_id": 12,
  "member_id": 3001,
  "contact_id": 9001,
  "type": "adjust",
  "amount": -20,
  "balance_after": 235,
  "remaining_amount": null,
  "expires_at": null,
  "expired_at": null,
  "source_type": "api",
  "source_id": null,
  "source_amount": null,
  "description": "Correction: duplicated ticket 10044",
  "metadata": null,
  "created_by_user_id": null,
  "created_at": "2026-11-07T14:20:00.000Z",
  "updated_at": "2026-11-07T14:20:00.000Z",
  "deleted_at": null,
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "5551234567" },
  "created_by_user": null
}
```

Returns the created `adjust` [transaction](#loyalty-transactions).

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | Number | Yes | ID of your organization |
| `member_id` | Number | Yes | ID of the card |
| `amount` | Number | Yes | Signed amount: positive adds, negative removes. Cannot be zero. |
| `description` | String | No | Reason shown in the history (up to 500 characters). Defaults to `Manual credit` or `Manual debit` |
| `idempotency_key` | String | No | Your unique key for this adjustment (up to 120 characters). Sending the same key again returns the first transaction and does not move the balance twice. |

#### Behavior

- Points and stamps are whole numbers (decimals are rounded down); cashback and gift card balances keep two decimals.
- A positive adjustment on a points, stamps or membership program with `expiration_days` expires after that many days, like earned balance. Cashback and gift card balances do not expire.
- A debit cannot leave the balance below zero.

#### Errors

| Message | Cause |
|---------|-------|
| `Member not found in this organization` | `member_id` does not belong to `organization_id` |
| `Amount must be a non-zero number` | `amount` is `0` or not a number |
| `Insufficient balance` | The debit is larger than the balance |
| `Nothing to adjust` | The amount rounds to zero (e.g. `0.4` points) |

---

## MCP Tool Connections

<a id="mcp-tool-connections"></a>

### MCP Tool Connections overview

Source: https://www.achieveapex.com/docs/api-reference/mcp-tool-connections

AI assistants can call tools from external Model Context Protocol (MCP) servers. A connection is not a separate resource: it is an item of the assistant's `mcp_tools` array. Use the connection test to check a server and read its tools, then save the connection on the assistant.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/mcp-tool-connection-proxy` | [Test an MCP connection](#mcp-tool-connections--test) |
| `PATCH` | `/ai-assistants/:id` | [Save connections on an assistant](#ai-assistants--update) |

#### The MCP connection object

```json
{
  "url": "https://mcp.example.com/v1",
  "label": "Knowledge Base MCP",
  "description": "Searches company knowledge base records",
  "authentication_type": "api_key",
  "api_key": "mcp_live_key",
  "custom_headers": null,
  "oauth2_config": null,
  "enabled_tools": ["search_articles"],
  "tools": [
    {
      "name": "search_articles",
      "description": "Search knowledge base articles",
      "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } } }
    }
  ],
  "needs_reauthorization": false
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `url` | string | Required. MCP server URL (Streamable HTTP). |
| `label` | string | Required. Display name. |
| `description` | string \| null | What the server provides. |
| `authentication_type` | string | Required. `none`, `api_key`, `custom_headers` or `oauth2`. |
| `api_key` | string \| null | Sent as `Authorization: Bearer <api_key>` when `authentication_type` is `api_key`. |
| `custom_headers` | array \| null | `{ key, value }` headers sent when `authentication_type` is `custom_headers`. |
| `oauth2_config` | object \| null | For `oauth2`: `authorization_server_url`, `client_id`, `client_secret`, `access_token`, `refresh_token`, `token_expiry`, `resource_uri`, `scopes`. `access_token` is sent as a Bearer token. |
| `enabled_tools` | string[] \| null | Names of the tools the assistant may use. |
| `tools` | array \| null | Tool definitions returned by the server: `name`, `description`, `inputSchema`. |
| `needs_reauthorization` | boolean \| null | Set when the OAuth2 authorization must be renewed. |

Credentials are stored on the assistant and returned when you read it; treat assistant responses as sensitive.

#### Save a server on an assistant

```bash
curl -X PATCH https://integrations.achieveapex.com/ai-assistants/123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_tools": [
      {
        "url": "https://mcp.example.com/v1",
        "label": "Knowledge Base MCP",
        "authentication_type": "api_key",
        "api_key": "mcp_live_key",
        "enabled_tools": ["search_articles"],
        "tools": [
          {
            "name": "search_articles",
            "description": "Search knowledge base articles",
            "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } } }
          }
        ]
      }
    ]
  }'
```

`mcp_tools` replaces the whole array, so include every server the assistant should keep.

#### Related

- [AI Assistants](#ai-assistants)

<a id="mcp-tool-connections--test"></a>

### Test an MCP connection

Source: https://www.achieveapex.com/docs/api-reference/mcp-tool-connections/test

Connect to an MCP server with the given credentials, call `tools/list`, and return the tools it offers. Nothing is saved.

#### Endpoint

`POST /mcp-tool-connection-proxy`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | MCP server URL. |
| `authentication_type` | string | No | `none`, `api_key`, `custom_headers` or `oauth2`. |
| `api_key` | string | No | Sent as a Bearer token when `authentication_type` is `api_key`. |
| `custom_headers` | array | No | `{ key, value }` headers, used when `authentication_type` is `custom_headers`. |
| `oauth2_config` | object | No | Its `access_token` is sent as a Bearer token when `authentication_type` is `oauth2`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/mcp-tool-connection-proxy \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mcp.example.com/v1",
    "authentication_type": "api_key",
    "api_key": "mcp_live_key_123"
  }'
```

#### Response

The call always succeeds at the HTTP level; check `success`.

```json
{
  "success": true,
  "status": 200,
  "statusText": "OK",
  "url": "https://mcp.example.com/v1",
  "headers": { "content-type": "application/json" },
  "data": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [ { "name": "search_knowledge_base" } ] } },
  "tools": [
    {
      "name": "search_knowledge_base",
      "description": "Searches the external knowledge base",
      "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] }
    }
  ]
}
```

| Field | Description |
|---|---|
| `success` | `true` when the server answered `tools/list`. |
| `tools` | Tools to save in the connection's `tools` and choose from for `enabled_tools`. |
| `data` | Raw JSON-RPC response (JSON or Server-Sent Events are both accepted). |

When the server cannot be reached, rejects the credentials or returns an MCP error:

```json
{
  "success": false,
  "status": 0,
  "statusText": "Network/Connection Error",
  "headers": {},
  "url": "https://mcp.example.com/v1",
  "data": "Failed to fetch tools: Unauthorized",
  "error": "Network Error: Failed to fetch tools: Unauthorized. This could be due to: invalid URL, network connectivity, SSL issues, authentication failure, or server not responding.",
  "tools": []
}
```

Then save the connection with [Update an AI assistant](#ai-assistants--update).

---

## Organization invitations

<a id="organizations-users-invites"></a>

### Organization invitations overview

Source: https://www.achieveapex.com/docs/api-reference/organizations-users-invites

An invitation asks someone, by email, to join your organization with a role. Creating one emails the person a link; when they accept it they become a member of the organization. Invitations expire 24 hours after they are created.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/organizations-users-invites` | [List invitations](#organizations-users-invites--list) |
| `GET` | `/organizations-users-invites/:id` | [Get an invitation](#organizations-users-invites--get) |
| `POST` | `/organizations-users-invites` | [Create an invitation](#organizations-users-invites--create) |
| `PATCH` | `/organizations-users-invites/:id` | [Update an invitation](#organizations-users-invites--update) |
| `DELETE` | `/organizations-users-invites/:id` | [Cancel an invitation](#organizations-users-invites--delete) |

Reads are limited to your API key's organization. Pass `organization_id` as a filter to work with one organization.

#### Who can invite

The checks use the role of the API key's user in the organization:

| Role | Can invite / cancel |
|---|---|
| `owner` | Any role (`owner`, `admin`, `member`). |
| `admin` | Only `member` invitations. |
| `member` | Nothing (`403 Forbidden`). |

#### The invitation object

```json
{
  "id": 77,
  "organization_id": 456,
  "email": "new.agent@example.com",
  "created_by_user_id": 789,
  "role": "member",
  "organization_role_id": null,
  "first_name": "Maria",
  "last_name": "Gomez",
  "avatar_url": null,
  "status": "pending",
  "expires_at": "2026-04-02T09:00:00.000Z",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null,
  "organization": { "id": 456, "name": "My Business" },
  "created_by_user": { "id": 789, "email": "ana@example.com", "first_name": "Ana", "last_name": "Lopez" },
  "user_exists": false
}
```

`organization`, `created_by_user` and `user_exists` (whether an AchieveApex account already exists for `email`) are added on list and get.

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization the person is invited to. Required on create; cannot be changed. |
| `email` | string | Email of the person invited. Required on create. Stored lowercase and trimmed. |
| `created_by_user_id` | integer | Read-only. User who sent the invitation (the API key's user). |
| `role` | string | Role the person gets on accepting: `owner`, `admin` or `member`. Required on create. |
| `organization_role_id` | integer \| null | Custom role (granular permissions) assigned on accepting, if any. |
| `first_name` | string \| null | First name to pre-fill on the new user's profile. Max 255 characters. |
| `last_name` | string \| null | Last name to pre-fill on the new user's profile. Max 255 characters. |
| `avatar_url` | string \| null | Profile picture to pre-fill. Must be a file uploaded for this organization's invitations (a key starting with `organizations/<organization_id>/invites/`). |
| `status` | string | Read-only on create. `pending`, `accepted` or `rejected`. Starts as `pending`. |
| `expires_at` | string (date-time) | Read-only on create. 24 hours after creation. Expired invitations cannot be accepted. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the invitation is cancelled. |

#### Related

- [Organizations](#organizations)

<a id="organizations-users-invites--list"></a>

### List invitations

Source: https://www.achieveapex.com/docs/api-reference/organizations-users-invites/list

Returns a paginated list of invitations.

#### Endpoint

`GET /organizations-users-invites`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only invitations of this organization. |
| `status` | string | No | `pending`, `accepted` or `rejected`. |
| any invitation field | mixed | No | Filter with Feathers syntax, e.g. `email=new.agent@example.com`, `expires_at[$gte]=2026-04-01T00:00:00Z`. |
| `mine` | boolean | No | `true` returns the pending, unexpired invitations sent to the API key user's own email, in any organization. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[created_at]=-1`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/organizations-users-invites \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'status=pending' \
  --data-urlencode '$sort[created_at]=-1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 77,
      "organization_id": 456,
      "email": "new.agent@example.com",
      "created_by_user_id": 789,
      "role": "member",
      "organization_role_id": null,
      "first_name": "Maria",
      "last_name": "Gomez",
      "avatar_url": null,
      "status": "pending",
      "expires_at": "2026-04-02T09:00:00.000Z",
      "created_at": "2026-04-01T09:00:00.000Z",
      "updated_at": "2026-04-01T09:00:00.000Z",
      "deleted_at": null,
      "organization": { "id": 456, "name": "My Business" },
      "created_by_user": { "id": 789, "email": "ana@example.com", "first_name": "Ana", "last_name": "Lopez" },
      "user_exists": false
    }
  ]
}
```

<a id="organizations-users-invites--get"></a>

### Get an invitation

Source: https://www.achieveapex.com/docs/api-reference/organizations-users-invites/get

Returns one invitation by ID.

#### Endpoint

`GET /organizations-users-invites/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/organizations-users-invites/77 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [invitation object](#organizations-users-invites).

```json
{
  "id": 77,
  "organization_id": 456,
  "email": "new.agent@example.com",
  "created_by_user_id": 789,
  "role": "member",
  "organization_role_id": null,
  "first_name": "Maria",
  "last_name": "Gomez",
  "avatar_url": null,
  "status": "pending",
  "expires_at": "2026-04-02T09:00:00.000Z",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null,
  "organization": { "id": 456, "name": "My Business" },
  "created_by_user": { "id": 789, "email": "ana@example.com", "first_name": "Ana", "last_name": "Lopez" },
  "user_exists": false
}
```

<a id="organizations-users-invites--create"></a>

### Create an invitation

Source: https://www.achieveapex.com/docs/api-reference/organizations-users-invites/create

Invites a person by email to join the organization. The API sets `status` to `pending` and `expires_at` to 24 hours from now, and emails the person a link to accept.

#### Endpoint

`POST /organizations-users-invites`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to invite the person to. |
| `email` | string | Yes | Email of the person. |
| `role` | string | Yes | `owner`, `admin` or `member`. Admins can only invite `member`. |
| `organization_role_id` | integer | No | Custom role to assign on accepting. |
| `first_name` | string | No | Pre-filled first name. |
| `last_name` | string | No | Pre-filled last name. |
| `avatar_url` | string | No | Pre-filled profile picture, uploaded for this organization's invitations. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/organizations-users-invites \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "email": "new.agent@example.com",
    "role": "member",
    "first_name": "Maria",
    "last_name": "Gomez"
  }'
```

#### Response

```json
{
  "id": 77,
  "organization_id": 456,
  "email": "new.agent@example.com",
  "created_by_user_id": 789,
  "role": "member",
  "organization_role_id": null,
  "first_name": "Maria",
  "last_name": "Gomez",
  "avatar_url": null,
  "status": "pending",
  "expires_at": "2026-04-02T09:00:00.000Z",
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-04-01T09:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | The plan's seat limit is reached (active members plus pending invitations), `avatar_url` is not an invitation upload of this organization, or a field is invalid. |
| `403 Forbidden` | The key's user is a `member`, is an `admin` inviting a non-member role, or does not belong to the organization. |
| `500 Internal Server Error` | The email already belongs to a member of the organization (message `User is already a member of this organization`). |

<a id="organizations-users-invites--update"></a>

### Update an invitation

Source: https://www.achieveapex.com/docs/api-reference/organizations-users-invites/update

Partially updates a pending invitation, for example to change the role or the pre-filled name before the person accepts. `organization_id`, `created_by_user_id` and the invitation token cannot be changed.

Accepting or rejecting (`status: "accepted"` / `"rejected"`) is done by the invited person from the link in the email; it only works for the person the invitation was sent to.

#### Endpoint

`PATCH /organizations-users-invites/:id`

#### Body

Any of `role`, `organization_role_id`, `first_name`, `last_name`, `avatar_url`, `email`.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/organizations-users-invites/77 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'
```

#### Response

Returns the updated [invitation object](#organizations-users-invites).

```json
{
  "id": 77,
  "organization_id": 456,
  "email": "new.agent@example.com",
  "role": "admin",
  "status": "pending",
  "expires_at": "2026-04-02T09:00:00.000Z",
  "updated_at": "2026-04-01T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Accepting an invitation that expired or is not `pending`. |
| `403 Forbidden` | Trying to move the invitation to another organization, or to accept/reject an invitation sent to a different email. |

<a id="organizations-users-invites--delete"></a>

### Cancel an invitation

Source: https://www.achieveapex.com/docs/api-reference/organizations-users-invites/delete

Cancels an invitation. This is a soft delete: the invitation gets a `deleted_at` timestamp and no longer appears in list or get.

Owners can cancel any invitation; admins only `member` invitations; members none.

#### Endpoint

`DELETE /organizations-users-invites/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/organizations-users-invites/77 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the cancelled [invitation object](#organizations-users-invites) with `deleted_at` set.

```json
{
  "id": 77,
  "organization_id": 456,
  "email": "new.agent@example.com",
  "role": "member",
  "status": "pending",
  "deleted_at": "2026-04-01T11:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The key's user is a `member`, or an `admin` cancelling a non-member invitation. |

---

## Organizations

<a id="organizations"></a>

### Organizations overview

Source: https://www.achieveapex.com/docs/api-reference/organizations

An organization is your AchieveApex workspace: it owns every contact, deal, conversation and setting. Use this resource to read the organization's settings, wallet balance, plan and usage limits, and to update its general settings.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/organizations` | [List organizations](#organizations--list) |
| `GET` | `/organizations/:id` | [Get an organization](#organizations--get) |
| `PATCH` | `/organizations/:id` | [Update an organization](#organizations--update) |

You can only read and update the organizations the API key's user belongs to.

#### The organization object

```json
{
  "id": 456,
  "name": "My Business",
  "timezone": "America/Bogota",
  "logo_url": "organizations/456/logo.png",
  "default_locale": "es",
  "default_phone_country_iso": "CO",
  "default_phone_country_code": "+57",
  "wallet_balance": "42.350000",
  "wallet_auto_recharge_enabled": true,
  "wallet_auto_recharge_minimum": "10.00",
  "wallet_auto_recharge_amount": "50.00",
  "wallet_auto_recharge_max_per_day": 3,
  "wallet_auto_recharge_max_per_30_days": 20,
  "wallet_auto_recharge_disabled_message": null,
  "channel_webchat_enabled": true,
  "mcp_enabled": true,
  "subscription_plan_name": "Pro",
  "subscription_status": "active",
  "subscription_amount": "99.00",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "subscription_current_period_start": "2026-04-01T00:00:00.000Z",
  "subscription_current_period_end": "2026-05-01T00:00:00.000Z",
  "subscription_canceled_at": null,
  "subscription_cancel_at": null,
  "subscription_cancel_at_period_end": false,
  "rate_limit_enabled": true,
  "rate_limit_max_requests": 1000,
  "rate_limit_window_seconds": 3600,
  "automation_limit_daily": null,
  "automation_limit_monthly": null,
  "automation_upgrade_needed_message": null,
  "automation_upgrade_needed_reason": null,
  "created_by_user_id": 789,
  "created_at": "2025-01-15T10:30:20.391Z",
  "updated_at": "2026-04-01T00:00:00.000Z",
  "deleted_at": null
}
```

Numeric money columns (`wallet_balance`, `wallet_auto_recharge_minimum`, `wallet_auto_recharge_amount`, `subscription_amount`) are decimal columns and may be returned as strings.

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Organization name. |
| `timezone` | string | IANA timezone, e.g. `America/Bogota`. Default `UTC`. Used for activities, reminders and daily limits. |
| `logo_url` | string \| null | Logo URL or storage key. |
| `default_locale` | string | Default language of the organization: `en` or `es`. Default `en`. |
| `default_phone_country_iso` | string | Default phone country, e.g. `US`. Default `US`. |
| `default_phone_country_code` | string | Default dialing code, e.g. `+1`. Default `+1`. |
| `wallet_balance` | number | Read-only. Prepaid wallet balance in USD, used for AI, messaging and voice usage. Default `0`. |
| `wallet_auto_recharge_enabled` | boolean | Recharge the wallet automatically when it falls below `wallet_auto_recharge_minimum`. Default `false`. |
| `wallet_auto_recharge_minimum` | number \| null | Balance (USD) that triggers an automatic recharge. See the validation rules in [Update an organization](#organizations--update). |
| `wallet_auto_recharge_amount` | number \| null | Amount (USD) charged on each automatic recharge. Must be greater than the minimum. |
| `wallet_auto_recharge_max_per_day` | number \| null | Maximum automatic recharges in a rolling 24 hours. |
| `wallet_auto_recharge_max_per_30_days` | number \| null | Maximum automatic recharges in a rolling 30 days. |
| `wallet_auto_recharge_disabled_message` | string \| null | Read-only. Why automatic recharge was turned off by the system. Cleared when you enable it again. |
| `channel_webchat_enabled` | boolean | Whether the webchat widget channel is enabled. Default `false`. |
| `mcp_enabled` | boolean | Whether the organization can be used from AI connectors through the AchieveApex MCP server. Default `false`. |
| `subscription_plan_name` | string \| null | Read-only. Current plan. Default `Free`. |
| `subscription_status` | string \| null | Read-only. `active`, `canceled`, `past_due`, `trialing`, `incomplete` or `incomplete_expired`. |
| `subscription_amount` | number \| null | Read-only. Price of the plan per billing period. |
| `billing_interval` | string \| null | Read-only. `day`, `week`, `month` or `year`. |
| `billing_interval_count` | number \| null | Read-only. Number of intervals per billing period. |
| `subscription_current_period_start` | string (date-time) \| null | Read-only. Start of the current billing period. |
| `subscription_current_period_end` | string (date-time) \| null | Read-only. End of the current billing period. |
| `subscription_canceled_at` | string (date-time) \| null | Read-only. When the subscription was canceled. |
| `subscription_cancel_at` | string (date-time) \| null | Read-only. When a scheduled cancellation takes effect. |
| `subscription_cancel_at_period_end` | boolean \| null | Read-only. Whether the subscription ends at the end of the current period. |
| `rate_limit_enabled` | boolean | Read-only. Whether API key requests are rate limited. Default `true`. |
| `rate_limit_max_requests` | number \| null | Read-only. Requests allowed per window. Default `1000`. |
| `rate_limit_window_seconds` | number \| null | Read-only. Rate limit window in seconds. Default `3600`. |
| `automation_limit_daily` | number \| null | Read-only. Automation runs allowed per day (null = the plan default). |
| `automation_limit_monthly` | number \| null | Read-only. Automation runs allowed per month (null = the plan default). |
| `automation_upgrade_needed_message` | string \| null | Read-only. Message shown when an automation limit was reached. |
| `automation_upgrade_needed_reason` | string \| null | Read-only. `daily_limit_reached`, `monthly_limit_reached` or `null`. |
| `created_by_user_id` | integer | Read-only. User who created the organization. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the organization is deleted. |

#### Related

- [Organization invitations](#organizations-users-invites)
- [Errors](#organizations--errors)

<a id="organizations--list"></a>

### List organizations

Source: https://www.achieveapex.com/docs/api-reference/organizations/list

Returns the organizations the API key's user belongs to.

#### Endpoint

`GET /organizations`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| any organization field | mixed | No | Filter with Feathers syntax, e.g. `id=456`, `subscription_status=active`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. |
| `$select[]` | string | No | Only return these fields, e.g. `$select[]=id&$select[]=name`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/organizations \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode '$select[]=id' \
  --data-urlencode '$select[]=name' \
  --data-urlencode '$select[]=timezone' \
  --data-urlencode '$sort[name]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 456,
      "name": "My Business",
      "timezone": "America/Bogota"
    }
  ]
}
```

Without `$select`, each item is a full [organization object](#organizations).

<a id="organizations--get"></a>

### Get an organization

Source: https://www.achieveapex.com/docs/api-reference/organizations/get

Returns one organization by ID, plus its current API rate limit and automation usage.

#### Endpoint

`GET /organizations/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/organizations/456 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [organization object](#organizations) with three extra objects:

- `rate_limit_status`: usage of the API key rate limit in the current window.
- `mcp_rate_limit_status`: the same for requests made through the MCP server.
- `automation_usage_status`: automation runs used today and this month.

```json
{
  "id": 456,
  "name": "My Business",
  "timezone": "America/Bogota",
  "subscription_plan_name": "Pro",
  "subscription_status": "active",
  "wallet_balance": "42.350000",
  "rate_limit_enabled": true,
  "rate_limit_max_requests": 1000,
  "rate_limit_window_seconds": 3600,
  "deleted_at": null,
  "rate_limit_status": {
    "enabled": true,
    "current": 120,
    "remaining": 880,
    "limit": 1000,
    "window_seconds": 3600,
    "reset_at": "2026-04-01T11:00:00.000Z",
    "percentage_used": 12
  },
  "mcp_rate_limit_status": {
    "enabled": true,
    "current": 4,
    "remaining": 996,
    "limit": 1000,
    "window_seconds": 3600,
    "reset_at": "2026-04-01T11:00:00.000Z",
    "percentage_used": 0
  },
  "automation_usage_status": {
    "daily_current": 35,
    "daily_limit": 1000,
    "daily_remaining": 965,
    "daily_reset_at": "2026-04-02T05:00:00.000Z",
    "percentage_daily_used": 4,
    "monthly_current": 410,
    "monthly_limit": 20000,
    "monthly_remaining": 19590,
    "monthly_reset_at": "2026-05-01T05:00:00.000Z",
    "percentage_monthly_used": 2
  }
}
```

When rate limiting is disabled, `rate_limit_status` and `mcp_rate_limit_status` are `{ "enabled": false, "message": "Rate limiting is disabled for this organization" }`.

<a id="organizations--update"></a>

### Update an organization

Source: https://www.achieveapex.com/docs/api-reference/organizations/update

Partially updates an organization's settings.

#### Endpoint

`PATCH /organizations/:id`

#### Body

| Name | Type | Description |
|---|---|---|
| `name` | string | Organization name. |
| `timezone` | string | IANA timezone. |
| `logo_url` | string | Logo URL or storage key. |
| `default_locale` | string | `en` or `es`. |
| `default_phone_country_iso` | string | e.g. `US`. |
| `default_phone_country_code` | string | e.g. `+1`. |
| `wallet_auto_recharge_enabled` | boolean | Turn automatic wallet recharge on or off. |
| `wallet_auto_recharge_minimum` | number | Recharge threshold in USD. |
| `wallet_auto_recharge_amount` | number | Recharge amount in USD. |
| `wallet_auto_recharge_max_per_day` | number | Maximum automatic recharges in 24 hours. |
| `wallet_auto_recharge_max_per_30_days` | number | Maximum automatic recharges in 30 days. |
| `channel_webchat_enabled` | boolean | Enable the webchat channel. |
| `mcp_enabled` | boolean | Allow access through the MCP server. |

Billing, subscription, wallet balance, rate limit and automation limit fields are read-only: they are ignored if you send them.

##### Automatic recharge rules

When you enable automatic recharge or change its threshold:

- `wallet_auto_recharge_minimum` must be at least the platform minimum threshold and not below the organization's recent average daily usage.
- `wallet_auto_recharge_amount` must be greater than `wallet_auto_recharge_minimum` and large enough to cover several days of average usage.

The error message states the exact minimum allowed for your organization.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/organizations/456 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/Mexico_City",
    "default_locale": "es"
  }'
```

#### Response

Returns the updated [organization object](#organizations).

```json
{
  "id": 456,
  "name": "My Business",
  "timezone": "America/Mexico_City",
  "default_locale": "es",
  "updated_at": "2026-04-02T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | An invalid value (e.g. `default_locale` not `en`/`es`), an unknown field, or an automatic recharge configuration that breaks the rules above. |

<a id="organizations--errors"></a>

### Organizations errors

Source: https://www.achieveapex.com/docs/api-reference/organizations/errors

Errors use the standard Feathers error format.

```json
{
  "name": "BadRequest",
  "message": "wallet_auto_recharge_amount must be greater than wallet_auto_recharge_minimum",
  "code": 400,
  "className": "bad-request"
}
```

| Status | Meaning |
|---|---|
| `400 Bad Request` | Invalid body or query, including invalid automatic recharge settings. |
| `401 Not Authenticated` | The API key is invalid or inactive. |
| `403 Forbidden` | No API key was sent, or the key's user does not belong to the organization. |
| `404 Not Found` | The organization does not exist or was deleted. |
| `500 Internal Server Error` | Unexpected server error. |

---

## Pipeline stages

<a id="pipeline-stages"></a>

### Pipeline stages overview

Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages

A stage is one column of a [pipeline](#pipelines), in a given `order`. Deals, conversations and support tickets point to their current stage with `pipeline_stage_id`.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/pipeline-stages` | [List pipeline stages](#pipeline-stages--list) |
| `GET` | `/pipeline-stages/:id` | [Get a pipeline stage](#pipeline-stages--get) |
| `POST` | `/pipeline-stages` | [Create a pipeline stage](#pipeline-stages--create) |
| `PATCH` | `/pipeline-stages/:id` | [Update a pipeline stage](#pipeline-stages--update) |
| `DELETE` | `/pipeline-stages/:id` | [Delete a pipeline stage](#pipeline-stages--delete) |

Reads are limited to your API key's organization and to stages of pipelines the key's user can see (see [pipeline visibility](#pipelines)). Creating, updating and deleting stages is not allowed when the key's user has the `member` role in the organization.

#### The pipeline stage object

```json
{
  "id": 101,
  "name": "Qualified",
  "pipeline_id": 10,
  "organization_id": 456,
  "order": 1,
  "rotting_days": 14,
  "created_by_user_id": 789,
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-01-10T12:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Stage name. Required on create. |
| `pipeline_id` | integer | Pipeline the stage belongs to. Required on create. |
| `organization_id` | integer | Organization that owns the stage. Required on create. |
| `order` | number | Position in the pipeline, starting at `0`. Required on create. |
| `rotting_days` | number \| null | Deal pipelines: days after which a deal that has not moved is shown as rotting. |
| `created_by_user_id` | integer | Read-only. User who created the stage (the API key's user). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the stage is deleted. |

#### Related

- [Pipelines](#pipelines)
- [Deals](#deals)
- [Conversations](#conversations)
- [Support tickets](#support-tickets)

<a id="pipeline-stages--list"></a>

### List pipeline stages

Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages/list

Returns stages, usually those of one pipeline sorted by `order`.

#### Endpoint

`GET /pipeline-stages`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `pipeline_id` | integer | No | Only stages of this pipeline. Use `pipeline_id[$in][]=10&pipeline_id[$in][]=11` for several. |
| `organization_id` | integer | No | Only stages of this organization. |
| any stage field | mixed | No | Filter with Feathers syntax, e.g. `name=Qualified`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Usually `$sort[order]=1`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/pipeline-stages \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'pipeline_id=10' \
  --data-urlencode '$sort[order]=1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 2,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 100,
      "name": "New",
      "pipeline_id": 10,
      "organization_id": 456,
      "order": 0,
      "rotting_days": null,
      "created_by_user_id": 789,
      "created_at": "2026-01-10T12:00:00.000Z",
      "updated_at": "2026-01-10T12:00:00.000Z",
      "deleted_at": null
    },
    {
      "id": 101,
      "name": "Qualified",
      "pipeline_id": 10,
      "organization_id": 456,
      "order": 1,
      "rotting_days": 14,
      "created_by_user_id": 789,
      "created_at": "2026-01-10T12:00:00.000Z",
      "updated_at": "2026-01-10T12:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

Stages of private pipelines the key's user cannot see are left out.

<a id="pipeline-stages--get"></a>

### Get a pipeline stage

Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages/get

Returns one stage by ID.

#### Endpoint

`GET /pipeline-stages/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/pipeline-stages/101 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [pipeline stage object](#pipeline-stages).

```json
{
  "id": 101,
  "name": "Qualified",
  "pipeline_id": 10,
  "organization_id": 456,
  "order": 1,
  "rotting_days": 14,
  "created_by_user_id": 789,
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-01-10T12:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The stage belongs to a private pipeline the key's user cannot see. |
| `404 Not Found` | No stage with this ID, or it was deleted. |

<a id="pipeline-stages--create"></a>

### Create a pipeline stage

Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages/create

Adds a stage to a pipeline. To append it at the end, set `order` to the current number of stages.

#### Endpoint

`POST /pipeline-stages`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization of the pipeline. |
| `pipeline_id` | integer | Yes | Pipeline to add the stage to. |
| `name` | string | Yes | Stage name. |
| `order` | number | Yes | Position, starting at `0`. Other stages are not reordered automatically. |
| `rotting_days` | number | No | Deal pipelines: rotting threshold in days. |

`created_by_user_id` is set to the API key's user.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/pipeline-stages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "pipeline_id": 10,
    "name": "Negotiation",
    "order": 2,
    "rotting_days": 7
  }'
```

#### Response

```json
{
  "id": 102,
  "name": "Negotiation",
  "pipeline_id": 10,
  "organization_id": 456,
  "order": 2,
  "rotting_days": 7,
  "created_by_user_id": 789,
  "created_at": "2026-02-01T10:00:00.000Z",
  "updated_at": "2026-02-01T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | A required field is missing or a value is invalid. |
| `403 Forbidden` | The API key's user has the `member` role in the organization. |

<a id="pipeline-stages--update"></a>

### Update a pipeline stage

Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages/update

Partially updates a stage: rename it, change `rotting_days`, or change `order` when reordering columns (patch each stage with its new index).

#### Endpoint

`PATCH /pipeline-stages/:id`

#### Body

Any of `name`, `order`, `rotting_days` (send `null` to clear it).

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/pipeline-stages/101 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discovery",
    "order": 0
  }'
```

#### Response

Returns the updated [pipeline stage object](#pipeline-stages).

```json
{
  "id": 101,
  "name": "Discovery",
  "pipeline_id": 10,
  "organization_id": 456,
  "order": 0,
  "rotting_days": 14,
  "updated_at": "2026-02-02T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The API key's user has the `member` role in the organization. |

<a id="pipeline-stages--delete"></a>

### Delete a pipeline stage

Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages/delete

Deletes a stage. This is a soft delete: the stage gets a `deleted_at` timestamp and no longer appears in list or get. What happens to the records in the stage depends on the pipeline type:

| Pipeline type | Records in the stage |
|---|---|
| `deal` | Required: pass `move_deals_to_stage_id` with another stage of the same pipeline. The deals are moved there (and their stage history updated) before the stage is deleted. |
| `conversation` | Optional: pass `move_conversations_to_stage_id` to move them to another stage of the same pipeline. Without it (or with `unassigned`), the conversations stay in the pipeline with no stage. |
| `ticket` | The stage cannot be deleted while it has support tickets. Move them first. |

#### Endpoint

`DELETE /pipeline-stages/:id`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `move_deals_to_stage_id` | integer | When the deal stage has deals | Destination stage in the same pipeline. |
| `move_conversations_to_stage_id` | integer \| `unassigned` | No | Destination stage in the same pipeline for conversations. |

#### Request

```bash
curl -X DELETE "https://integrations.achieveapex.com/pipeline-stages/101?move_deals_to_stage_id=100" \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [pipeline stage object](#pipeline-stages) with `deleted_at` set.

```json
{
  "id": 101,
  "name": "Qualified",
  "pipeline_id": 10,
  "organization_id": 456,
  "order": 1,
  "deleted_at": "2026-02-03T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Deals are in the stage and no destination was given, the destination is the same stage or belongs to another pipeline, or the stage still has support tickets. |
| `403 Forbidden` | The API key's user has the `member` role in the organization. |

---

## Pipelines

<a id="pipelines"></a>

### Pipelines overview

Source: https://www.achieveapex.com/docs/api-reference/pipelines

A pipeline is an ordered set of [stages](#pipeline-stages) used to track deals, conversations or support tickets on a board. The `type` of the pipeline says which records it holds.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/pipelines` | [List pipelines](#pipelines--list) |
| `GET` | `/pipelines/:id` | [Get a pipeline](#pipelines--get) |
| `POST` | `/pipelines` | [Create a pipeline](#pipelines--create) |
| `PATCH` | `/pipelines/:id` | [Update a pipeline](#pipelines--update) |
| `DELETE` | `/pipelines/:id` | [Delete a pipeline](#pipelines--delete) |

Reads are limited to your API key's organization. Pass `organization_id` and `type` as filters.

#### Visibility and permissions

- A `public` pipeline is visible to every member of the organization. A `private` pipeline is only visible to its members (managed in the app) and to organization owners and admins. List and get apply this to the API key's user.
- Creating, updating and deleting pipelines is not allowed when the API key's user has the `member` role in the organization (`403 Forbidden`).

#### The pipeline object

```json
{
  "id": 10,
  "name": "Sales",
  "description": "New business pipeline",
  "type": "deal",
  "organization_id": 456,
  "created_by_user_id": 789,
  "config": { "defaultDealStatus": "open" },
  "visibility": "public",
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-01-10T12:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Display name. Required on create. |
| `description` | string | Description. |
| `type` | string | `deal`, `conversation` or `ticket`. Required on create. |
| `organization_id` | integer | Organization that owns the pipeline. Required on create. |
| `created_by_user_id` | integer | Read-only. User who created the pipeline (the API key's user). |
| `config` | object \| null | Settings. For `deal` pipelines the app stores `defaultDealStatus` (`open`, `won`, `lost` or `all`), the status filter applied when the board opens. For `conversation` pipelines, `channel_scope` lists the channels the pipeline accepts (see [Channel scope](#channel-scope-conversation-pipelines)). On update, `config` of a conversation pipeline is merged with the stored object. |
| `visibility` | string | `public` or `private`. Default `public`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the pipeline is deleted. |

#### Channel scope (conversation pipelines)

A conversation pipeline can accept conversations from only some channels. `config.channel_scope` is a list of keys:

| Key | Channel |
|---|---|
| `whatsapp:<whatsapp_channel_id>` | One WhatsApp number of the organization |
| `instagram` | Instagram |
| `messenger` | Messenger |
| `webchat` | Webchat |
| `sms` | SMS |

An empty or missing list means every channel, including channels connected later.

- [Listing conversations](#conversations--list) with `pipeline_id` or `incoming_pipeline_id` only returns conversations of the pipeline's channels.
- A conversation cannot be moved into a pipeline that does not accept its channel: [patching a conversation](#conversations--patch) returns `400` with `data.code = "PIPELINE_CHANNEL_NOT_ALLOWED"`.
- Removing channels that still have conversations in the pipeline requires saying where they go (`channel_scope_migration`, see [Update a pipeline](#pipelines--update)).

#### Related

- [Pipeline stages](#pipeline-stages)
- [Deals](#deals)
- [Conversations](#conversations)
- [Support tickets](#support-tickets)

<a id="pipelines--list"></a>

### List pipelines

Source: https://www.achieveapex.com/docs/api-reference/pipelines/list

Returns the pipelines the API key's user can see.

#### Endpoint

`GET /pipelines`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Only pipelines of this organization. |
| `type` | string | No | `deal`, `conversation` or `ticket`. |
| any pipeline field | mixed | No | Filter with Feathers syntax, e.g. `visibility=private`, `name=Sales`. |
| `$limit` | integer | No | Page size. Default 10, max 50. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/pipelines \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'type=deal' \
  --data-urlencode '$sort[name]=1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 10,
      "name": "Sales",
      "description": "New business pipeline",
      "type": "deal",
      "organization_id": 456,
      "created_by_user_id": 789,
      "config": { "defaultDealStatus": "open" },
      "visibility": "public",
      "created_at": "2026-01-10T12:00:00.000Z",
      "updated_at": "2026-01-10T12:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

To get the columns of a pipeline, [list its stages](#pipeline-stages--list) with `pipeline_id`.

<a id="pipelines--get"></a>

### Get a pipeline

Source: https://www.achieveapex.com/docs/api-reference/pipelines/get

Returns one pipeline by ID.

#### Endpoint

`GET /pipelines/:id`

#### Request

```bash
curl -G https://integrations.achieveapex.com/pipelines/10 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the [pipeline object](#pipelines).

```json
{
  "id": 10,
  "name": "Sales",
  "description": "New business pipeline",
  "type": "deal",
  "organization_id": 456,
  "created_by_user_id": 789,
  "config": { "defaultDealStatus": "open" },
  "visibility": "public",
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-01-10T12:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The pipeline is private and the API key's user is not a member, owner or admin. |
| `404 Not Found` | No pipeline with this ID, or it was deleted. |

<a id="pipelines--create"></a>

### Create a pipeline

Source: https://www.achieveapex.com/docs/api-reference/pipelines/create

Creates a pipeline. Add its columns afterwards with [Create a pipeline stage](#pipeline-stages--create).

#### Endpoint

`POST /pipelines`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Organization to create the pipeline in. |
| `name` | string | Yes | Display name. |
| `type` | string | Yes | `deal`, `conversation` or `ticket`. |
| `description` | string | No | Description. |
| `visibility` | string | No | `public` (default) or `private`. |
| `config` | object | No | Settings. Deal pipelines may set `defaultDealStatus` (`open`, `won`, `lost`, `all`). Conversation pipelines may set `channel_scope`, e.g. `["whatsapp:12", "instagram"]` ([channel scope](https://www.achieveapex.com/docs/api-reference/pipelines/overview#channel-scope-conversation-pipelines)); WhatsApp numbers must belong to the organization. |

`created_by_user_id` is set to the API key's user.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/pipelines \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Enterprise sales",
    "type": "deal",
    "config": { "defaultDealStatus": "open" }
  }'
```

#### Response

```json
{
  "id": 11,
  "name": "Enterprise sales",
  "description": null,
  "type": "deal",
  "organization_id": 456,
  "created_by_user_id": 789,
  "config": { "defaultDealStatus": "open" },
  "visibility": "public",
  "created_at": "2026-02-01T10:00:00.000Z",
  "updated_at": "2026-02-01T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `name`, `type` or `organization_id` is missing, or a value is invalid. |
| `403 Forbidden` | The API key's user has the `member` role in the organization. |

<a id="pipelines--update"></a>

### Update a pipeline

Source: https://www.achieveapex.com/docs/api-reference/pipelines/update

Partially updates a pipeline, e.g. to rename it, change its visibility or its `config`.

#### Endpoint

`PATCH /pipelines/:id`

#### Body

Any of `name`, `description`, `visibility`, `config`, `type`. For deal pipelines `config` replaces the stored object, so send the full object. For conversation pipelines `config` is merged with the stored object, and the body may also carry `channel_scope_migration` (see below).

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/pipelines/10 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales (EMEA)",
    "config": { "defaultDealStatus": "all" }
  }'
```

#### Request (conversation pipeline — channel scope)

Limit a conversation pipeline to one WhatsApp number and Instagram ([channel scope](https://www.achieveapex.com/docs/api-reference/pipelines/overview#channel-scope-conversation-pipelines)). Send `[]` to accept every channel again.

```bash
curl -X PATCH https://integrations.achieveapex.com/pipelines/10 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": { "channel_scope": ["whatsapp:12", "instagram"] }
  }'
```

If the pipeline still holds conversations of channels you are removing, the request fails with `400` and `data.code = "PIPELINE_SCOPE_CONFLICT"`, plus `data.total` and `data.by_channel` (`[{ "channel_key": "whatsapp:15", "count": 42 }]`). Repeat it with `channel_scope_migration` to say where they go:

| `channel_scope_migration` | Effect |
|---|---|
| `{ "action": "unassign" }` | The conversations leave every pipeline (they show in the Incoming column of the pipelines that accept their channel). |
| `{ "action": "move", "pipeline_id": 11, "pipeline_stage_id": 70 }` | They move to another conversation pipeline that accepts all those channels. `pipeline_stage_id` is optional (`null` = Incoming). |

```bash
curl -X PATCH https://integrations.achieveapex.com/pipelines/10 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": { "channel_scope": ["instagram"] },
    "channel_scope_migration": { "action": "unassign" }
  }'
```

After a migration the response also has `channel_scope_migrated_count`, the number of conversations moved.

#### Response

Returns the updated [pipeline object](#pipelines).

```json
{
  "id": 10,
  "name": "Sales (EMEA)",
  "type": "deal",
  "organization_id": 456,
  "config": { "defaultDealStatus": "all" },
  "visibility": "public",
  "updated_at": "2026-02-02T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid channel key, a WhatsApp number of another organization, `PIPELINE_SCOPE_CONFLICT` (see above), or a migration destination that does not accept the moved channels (`PIPELINE_CHANNEL_NOT_ALLOWED`). |
| `403 Forbidden` | The API key's user has the `member` role in the organization. |

<a id="pipelines--delete"></a>

### Delete a pipeline

Source: https://www.achieveapex.com/docs/api-reference/pipelines/delete

Deletes a pipeline. This is a soft delete: the pipeline gets a `deleted_at` timestamp and no longer appears in list or get.

A `deal` or `conversation` pipeline that still holds active deals or conversations cannot be deleted: move them to another pipeline first (update each deal's `pipeline_id` and `pipeline_stage_id`).

#### Endpoint

`DELETE /pipelines/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/pipelines/10 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [pipeline object](#pipelines) with `deleted_at` set.

```json
{
  "id": 10,
  "name": "Sales",
  "type": "deal",
  "organization_id": 456,
  "deleted_at": "2026-02-03T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | The pipeline still has deals or conversations. The error `data` contains `code: "PIPELINE_HAS_RECORDS"`, `count` and `type`. |
| `403 Forbidden` | The API key's user has the `member` role in the organization. |

```json
{
  "name": "BadRequest",
  "message": "This pipeline still has 12 deals. Move them to another pipeline before deleting it.",
  "code": 400,
  "className": "bad-request",
  "data": { "code": "PIPELINE_HAS_RECORDS", "count": 12, "type": "deal" }
}
```

---

## Predefined messages

<a id="conversation-predefined-messages"></a>

### Predefined messages overview

Source: https://www.achieveapex.com/docs/api-reference/conversation-predefined-messages

Predefined messages are the organization's canned replies (text or media) that agents insert from the conversation composer.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/conversation-predefined-messages` | [List predefined messages](#conversation-predefined-messages--list) |
| `GET` | `/conversation-predefined-messages/:id` | [Get a predefined message](#conversation-predefined-messages--get) |
| `POST` | `/conversation-predefined-messages` | [Create a predefined message](#conversation-predefined-messages--create) |
| `PATCH` | `/conversation-predefined-messages/:id` | [Update a predefined message](#conversation-predefined-messages--update) |
| `DELETE` | `/conversation-predefined-messages/:id` | [Delete a predefined message](#conversation-predefined-messages--delete) |

#### The predefined message object

```json
{
  "id": 42,
  "organization_id": 456,
  "title": "Business hours",
  "content": "We are open Monday to Friday, 9am to 6pm.",
  "message_type": "text",
  "media_url": null,
  "filename": null,
  "mime_type": null,
  "created_by_user_id": 12,
  "created_by_user": {
    "id": 12,
    "email": "carlos@example.com",
    "first_name": "Carlos",
    "last_name": "Ruiz",
    "avatar_url": null
  },
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-01-15T10:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization. Required on create; cannot be changed. |
| `title` | string | Short label shown in the picker. Required. |
| `content` | string | Text of the reply (caption for media). Required. |
| `message_type` | string | One of `text`, `image`, `video`, `document`, `audio`, `location`. Default `text`. |
| `media_url` | string \| null | Media of the reply: the storage key from an [upload URL](#s3-url-signing) of type `conversation-predefined-message`, or a full URL. |
| `filename` | string \| null | File name of the media. |
| `mime_type` | string \| null | MIME type of the media. |
| `created_by_user_id` | integer | Read-only. Author: always the API key's user on create. |
| `created_by_user` | object \| null | Read-only. Author's `id`, `email`, `first_name`, `last_name`, `avatar_url`. Added to every response. |
| `created_at` | string (date-time) | Read-only. |
| `updated_at` | string (date-time) | Read-only. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when deleted. |

Only the author or an owner/admin of the organization can update or delete a predefined message.

<a id="conversation-predefined-messages--list"></a>

### List predefined messages

Source: https://www.achieveapex.com/docs/api-reference/conversation-predefined-messages/list

List the organization's canned replies.

#### Endpoint

`GET /conversation-predefined-messages`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization. Results are always limited to your API key's organization. |
| `message_type` | string | No | `text`, `image`, `video`, `document`, `audio` or `location`. |
| `created_by_user_id` | integer | No | Author. |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[title]` | `1` \| `-1` | No | Sort by title (the app lists them alphabetically). |

#### Request

```bash
curl -G https://integrations.achieveapex.com/conversation-predefined-messages \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode '$sort[title]=1' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 42,
      "organization_id": 456,
      "title": "Business hours",
      "content": "We are open Monday to Friday, 9am to 6pm.",
      "message_type": "text",
      "media_url": null,
      "filename": null,
      "mime_type": null,
      "created_by_user_id": 12,
      "created_by_user": { "id": 12, "email": "carlos@example.com", "first_name": "Carlos", "last_name": "Ruiz", "avatar_url": null },
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="conversation-predefined-messages--get"></a>

### Get a predefined message

Source: https://www.achieveapex.com/docs/api-reference/conversation-predefined-messages/get

Retrieve one canned reply by ID.

#### Endpoint

`GET /conversation-predefined-messages/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/conversation-predefined-messages/42 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 42,
  "organization_id": 456,
  "title": "Business hours",
  "content": "We are open Monday to Friday, 9am to 6pm.",
  "message_type": "text",
  "media_url": null,
  "filename": null,
  "mime_type": null,
  "created_by_user_id": 12,
  "created_by_user": { "id": 12, "email": "carlos@example.com", "first_name": "Carlos", "last_name": "Ruiz", "avatar_url": null },
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-01-15T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The ID does not exist, was deleted, or belongs to an organization your API key cannot access. |

<a id="conversation-predefined-messages--create"></a>

### Create a predefined message

Source: https://www.achieveapex.com/docs/api-reference/conversation-predefined-messages/create

Create a canned reply for the organization. The author (`created_by_user_id`) is always the API key's user.

#### Endpoint

`POST /conversation-predefined-messages`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. |
| `title` | string | Yes | Label shown in the picker. |
| `content` | string | Yes | Reply text (caption for media). |
| `message_type` | string | No | `text` (default), `image`, `video`, `document`, `audio` or `location`. |
| `media_url` | string | No | For media: the `s3PathWithoutBucket` of an [upload URL](#s3-url-signing--create) of type `conversation-predefined-message`, or a full URL. |
| `filename` | string | No | File name of the media. |
| `mime_type` | string | No | MIME type of the media. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/conversation-predefined-messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "title": "Business hours",
    "content": "We are open Monday to Friday, 9am to 6pm.",
    "message_type": "text"
  }'
```

#### Response

The created [predefined message](#conversation-predefined-messages):

```json
{
  "id": 43,
  "organization_id": 456,
  "title": "Business hours",
  "content": "We are open Monday to Friday, 9am to 6pm.",
  "message_type": "text",
  "media_url": null,
  "filename": null,
  "mime_type": null,
  "created_by_user_id": 12,
  "created_by_user": { "id": 12, "email": "carlos@example.com", "first_name": "Carlos", "last_name": "Ruiz", "avatar_url": null },
  "created_at": "2026-02-10T10:00:00.000Z",
  "updated_at": "2026-02-10T10:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | A required field is missing, `message_type` is not allowed, or an unknown field was sent. |

<a id="conversation-predefined-messages--update"></a>

### Update a predefined message

Source: https://www.achieveapex.com/docs/api-reference/conversation-predefined-messages/update

Partially update a canned reply. Only its author or an owner/admin of the organization can update it. `id`, `organization_id` and `created_by_user_id` are ignored if sent.

#### Endpoint

`PATCH /conversation-predefined-messages/:id`

#### Body

Any of `title`, `content`, `message_type`, `media_url`, `filename`, `mime_type` (see [Fields](#conversation-predefined-messages)).

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/conversation-predefined-messages/42 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Business hours (updated)",
    "content": "We are open Monday to Friday, 9am to 7pm."
  }'
```

#### Response

The updated [predefined message](#conversation-predefined-messages).

```json
{
  "id": 42,
  "organization_id": 456,
  "title": "Business hours (updated)",
  "content": "We are open Monday to Friday, 9am to 7pm.",
  "message_type": "text",
  "created_by_user_id": 12,
  "updated_at": "2026-02-10T11:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The API key's user is not the author nor an owner/admin of the organization. |
| `404 Not Found` | The predefined message does not exist or was deleted. |

<a id="conversation-predefined-messages--delete"></a>

### Delete a predefined message

Source: https://www.achieveapex.com/docs/api-reference/conversation-predefined-messages/delete

Delete a canned reply. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get responses. Only its author or an owner/admin of the organization can delete it.

#### Endpoint

`DELETE /conversation-predefined-messages/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/conversation-predefined-messages/42 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [predefined message](#conversation-predefined-messages) with `deleted_at` set.

```json
{
  "id": 42,
  "organization_id": 456,
  "title": "Business hours",
  "deleted_at": "2026-02-10T12:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | The API key's user is not the author nor an owner/admin of the organization. |
| `404 Not Found` | The predefined message does not exist or was already deleted. |

---

## Product categories

<a id="product-categories"></a>

### Product categories overview

Source: https://www.achieveapex.com/docs/api-reference/product-categories

Categories group the products of your catalog. A product points to its category with `product_category_id`.

#### Endpoints

The REST path of this resource is `/products-categories` (with an **s** in `products`).

| Method | Path | Description |
|---|---|---|
| `GET` | `/products-categories` | [List product categories](#product-categories--list) |
| `GET` | `/products-categories/:id` | [Get a product category](#product-categories--get) |
| `POST` | `/products-categories` | [Create a product category](#product-categories--create) |
| `PATCH` | `/products-categories/:id` | [Update a product category](#product-categories--update) |
| `DELETE` | `/products-categories/:id` | [Delete a product category](#product-categories--delete) |

The API key is scoped to one organization: reads are filtered to it automatically, and `organization_id` is required in the body on create.

#### The product category object

```json
{
  "id": 5,
  "name": "Subscriptions",
  "organization_id": 27,
  "created_at": "2026-03-15T10:30:20.391Z",
  "updated_at": "2026-03-15T10:30:20.391Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `name` | string | Category name. Required. |
| `organization_id` | integer | Organization that owns the category. Required on create. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the category is deleted. |

#### Related

- [Products](#products)

<a id="product-categories--list"></a>

### List product categories

Source: https://www.achieveapex.com/docs/api-reference/product-categories/list

Retrieve your organization's product categories.

#### Endpoint

`GET /products-categories`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | Exact category name. |
| `id[$in][]` | integer | No | Only these IDs. |
| `$limit` | integer | No | Page size (default 10, max 50). |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, for example `$sort[name]=1`. |
| `$select[]` | string | No | Return only these fields. |

Results are filtered to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/products-categories \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode '$limit=10' \
  --data-urlencode '$sort[name]=1'
```

#### Response

```json
{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 6,
      "name": "Hardware",
      "organization_id": 27,
      "created_at": "2026-03-15T10:32:15.845Z",
      "updated_at": "2026-03-15T10:32:15.845Z",
      "deleted_at": null
    },
    {
      "id": 5,
      "name": "Subscriptions",
      "organization_id": 27,
      "created_at": "2026-03-15T10:30:20.391Z",
      "updated_at": "2026-03-15T10:30:20.391Z",
      "deleted_at": null
    }
  ]
}
```

<a id="product-categories--get"></a>

### Get a product category

Source: https://www.achieveapex.com/docs/api-reference/product-categories/get

Retrieve one product category by ID.

#### Endpoint

`GET /products-categories/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/products-categories/5 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 5,
  "name": "Subscriptions",
  "organization_id": 27,
  "created_at": "2026-03-15T10:30:20.391Z",
  "updated_at": "2026-03-15T10:30:20.391Z",
  "deleted_at": null
}
```

To list the products of a category, call [`GET /products?product_category_id=5`](#products--list).

<a id="product-categories--create"></a>

### Create a product category

Source: https://www.achieveapex.com/docs/api-reference/product-categories/create

Create a category for your products.

#### Endpoint

`POST /products-categories`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `name` | string | Yes | Category name. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/products-categories \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Software Tools"
  }'
```

#### Response

```json
{
  "id": 8,
  "name": "Software Tools",
  "organization_id": 27,
  "created_at": "2026-03-22T16:15:44.782Z",
  "updated_at": "2026-03-22T16:15:44.782Z",
  "deleted_at": null
}
```

<a id="product-categories--update"></a>

### Update a product category

Source: https://www.achieveapex.com/docs/api-reference/product-categories/update

Rename a product category (partial update).

#### Endpoint

`PATCH /products-categories/:id`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | No | New category name. |

`organization_id` cannot be changed.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/products-categories/8 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Software Solutions"
  }'
```

#### Response

```json
{
  "id": 8,
  "name": "Software Solutions",
  "organization_id": 27,
  "created_at": "2026-03-22T16:15:44.782Z",
  "updated_at": "2026-03-22T16:20:12.345Z",
  "deleted_at": null
}
```

<a id="product-categories--delete"></a>

### Delete a product category

Source: https://www.achieveapex.com/docs/api-reference/product-categories/delete

Delete a product category. This is a soft delete: the category gets `deleted_at` and no longer appears in list or get.

#### Endpoint

`DELETE /products-categories/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/products-categories/8 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 8,
  "name": "Software Solutions",
  "organization_id": 27,
  "created_at": "2026-03-22T16:15:44.782Z",
  "updated_at": "2026-03-22T16:25:33.678Z",
  "deleted_at": "2026-03-22T16:25:33.678Z"
}
```

Products of the category are not deleted or changed: they keep their `product_category_id`. Patch them if you want to move them to another category.

<a id="product-categories--errors"></a>

### Error Handling

Source: https://www.achieveapex.com/docs/api-reference/product-categories/errors

The Product Categories API returns standard HTTP status codes and error messages.

#### Error Response

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

#### Status Codes

| Status Code | Description |
|-------------|-------------|
| `400 Bad Request` | Invalid parameters or request |
| `401 Unauthorized` | Missing or invalid authentication |
| `403 Forbidden` | Not authorized to access this organization's product categories |
| `404 Not Found` | Product category not found |
| `500 Internal Server Error` | Server error |

---

## Product media

<a id="product-media"></a>

### Product media overview

Source: https://www.achieveapex.com/docs/api-reference/product-media

Images and other files attached to a product. The file itself is stored in AchieveApex storage (uploaded with a signed URL); a product media record links it to the product and sets its display order.

#### Endpoints

The REST path of this resource is `/products-media` (with an **s** in `products`). `/product-media` does not exist and returns `404`.

| Method | Path | Description |
|---|---|---|
| `GET` | `/products-media` | [List product media](#product-media--list) |
| `GET` | `/products-media/:id` | [Get a product media item](#product-media--get) |
| `POST` | `/products-media` | [Upload product media](#product-media--create) |
| `PATCH` | `/products-media/:id` | [Update product media](#product-media--update) |
| `DELETE` | `/products-media/:id` | [Delete product media](#product-media--delete) |

The API key is scoped to one organization: reads are filtered to it automatically.

#### The product media object

```json
{
  "id": 456,
  "organization_id": 101,
  "product_id": 123,
  "position": 0,
  "file_name": "product-123-front.jpeg",
  "file_type": "image/jpeg",
  "file_size": 228072,
  "file_path": "org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
  "s3_key": "org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
  "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
  "created_at": "2026-08-19T20:11:31.563Z",
  "updated_at": "2026-08-19T20:11:31.560Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization of the product. On create it is always taken from the product. |
| `product_id` | integer | Product the file belongs to. Required. |
| `position` | integer | Display order (lowest first). The item with the lowest `position` is the product's main image. Default `0`. |
| `file_name` | string | Original file name. |
| `file_type` | string | MIME type, for example `image/jpeg`. |
| `file_size` | integer | File size in bytes. |
| `file_path` | string | Storage key of the file (the `s3PathWithoutBucket` returned by the signing step). |
| `s3_key` | string | Storage key of the file (same value as `file_path`). Used to delete the file. |
| `s3_path` | string | Full storage path, `s3://bucket/key` (the `s3Path` returned by the signing step). |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the item is deleted. |

#### Related

- [Products](#products)

<a id="product-media--list"></a>

### List product media

Source: https://www.achieveapex.com/docs/api-reference/product-media/list

Retrieve the media items of your organization, usually filtered by product.

#### Endpoint

`GET /products-media`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `product_id` | integer | No | Only media of this product. |
| `file_type` | string | No | Exact MIME type, for example `image/png`. |
| `$limit` | integer | No | Page size (default 10, max 50). |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, for example `$sort[position]=1`. |
| `$select[]` | string | No | Return only these fields. |

Results are filtered to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/products-media \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'product_id=123' \
  --data-urlencode '$limit=10' \
  --data-urlencode '$sort[position]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 456,
      "organization_id": 101,
      "product_id": 123,
      "position": 0,
      "file_name": "product-123-front.jpeg",
      "file_type": "image/jpeg",
      "file_size": 228072,
      "file_path": "org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
      "s3_key": "org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
      "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
      "created_at": "2026-08-19T20:11:31.563Z",
      "updated_at": "2026-08-19T20:11:31.560Z",
      "deleted_at": null
    }
  ]
}
```

<a id="product-media--get"></a>

### Get a product media item

Source: https://www.achieveapex.com/docs/api-reference/product-media/get

Retrieve one product media item by ID.

#### Endpoint

`GET /products-media/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/products-media/456 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 456,
  "organization_id": 101,
  "product_id": 123,
  "position": 0,
  "file_name": "product-123-front.jpeg",
  "file_type": "image/jpeg",
  "file_size": 228072,
  "file_path": "org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
  "s3_key": "org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
  "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260819T201130_product-123-front.jpeg",
  "created_at": "2026-08-19T20:11:31.563Z",
  "updated_at": "2026-08-19T20:11:31.560Z",
  "deleted_at": null
}
```

<a id="product-media--create"></a>

### Upload product media

Source: https://www.achieveapex.com/docs/api-reference/product-media/create

Attach a file to a product. Uploading is three steps: get a signed upload URL, upload the file to it, then create the media record.

#### Endpoint

`POST /products-media`

#### Step 1: Get a signed upload URL

```bash
curl -X POST https://integrations.achieveapex.com/s3-url-signing \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "product-media",
    "filename": "product-123-detail.png",
    "product_id": 123,
    "contentType": "image/png"
  }'
```

| Name | Type | Required | Description |
|---|---|---|---|
| `type` | string | Yes | `product-media`. |
| `filename` | string | Yes | Original file name. |
| `product_id` | integer | Yes | Product that owns the file. |
| `contentType` | string | No | MIME type of the file. |

```json
{
  "signedUrl": "https://achieveapex-organization-files.s3.amazonaws.com/...",
  "s3Path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3PathWithoutBucket": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "headers": { "Content-Type": "image/png" }
}
```

#### Step 2: Upload the file

```bash
curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: image/png" \
  --data-binary "@/path/to/product-123-detail.png"
```

#### Step 3: Create the media record

##### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). The stored value is always the product's organization. |
| `product_id` | integer | Yes | Product to attach the file to. |
| `file_name` | string | Yes | Original file name. |
| `file_type` | string | Yes | MIME type. |
| `file_path` | string | Yes | `s3PathWithoutBucket` from step 1. |
| `s3_key` | string | Yes | `s3PathWithoutBucket` from step 1 (same as `file_path`). |
| `s3_path` | string | Yes | `s3Path` from step 1. |
| `file_size` | integer | No | Size in bytes. |
| `position` | integer | No | Display order, lowest first. Default `0`. |

##### Request

```bash
curl -X POST https://integrations.achieveapex.com/products-media \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 101,
    "product_id": 123,
    "file_name": "product-123-detail.png",
    "file_type": "image/png",
    "file_size": 228072,
    "file_path": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
    "s3_key": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
    "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
    "position": 4
  }'
```

#### Response

```json
{
  "id": 459,
  "organization_id": 101,
  "product_id": 123,
  "position": 4,
  "file_name": "product-123-detail.png",
  "file_type": "image/png",
  "file_size": 228072,
  "file_path": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3_key": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "created_at": "2026-05-11T16:30:25.142Z",
  "updated_at": "2026-05-11T16:30:25.142Z",
  "deleted_at": null
}
```

#### Errors

| Status | Cause |
|---|---|
| `400 Bad Request` | `product_id is required`, or schema validation failed. |
| `403 Forbidden` | `organization_id` is missing or is not the API key's organization. |
| `500` | The product does not exist (`Could not fetch product details: …`). |

<a id="product-media--update"></a>

### Update product media

Source: https://www.achieveapex.com/docs/api-reference/product-media/update

Change a media item, usually its `position` to reorder a product's images (partial update).

#### Endpoint

`PATCH /products-media/:id`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `position` | integer | No | Display order, lowest first. |
| `file_name` | string | No | File name shown for the item. |

Other fields of the [product media object](#product-media) are also accepted, but changing `file_path`, `s3_key` or `s3_path` does not move the stored file. `organization_id` cannot be changed.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/products-media/459 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 0
  }'
```

#### Response

```json
{
  "id": 459,
  "organization_id": 101,
  "product_id": 123,
  "position": 0,
  "file_name": "product-123-detail.png",
  "file_type": "image/png",
  "file_size": 228072,
  "file_path": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3_key": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "created_at": "2026-05-11T16:30:25.142Z",
  "updated_at": "2026-05-11T16:45:12.215Z",
  "deleted_at": null
}
```

<a id="product-media--delete"></a>

### Delete product media

Source: https://www.achieveapex.com/docs/api-reference/product-media/delete

Delete a media item. The record is soft deleted (it gets `deleted_at` and no longer appears in list or get) and the stored file is removed.

#### Endpoint

`DELETE /products-media/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/products-media/459 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 459,
  "organization_id": 101,
  "product_id": 123,
  "position": 0,
  "file_name": "product-123-detail.png",
  "file_type": "image/png",
  "file_size": 228072,
  "file_path": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3_key": "org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "s3_path": "s3://achieveapex-organization-files/org_101/products/product_123/product-media_20260511T162632_product-123-detail.png",
  "created_at": "2026-05-11T16:30:25.142Z",
  "updated_at": "2026-05-11T16:45:12.215Z",
  "deleted_at": "2026-05-12T09:00:00.000Z"
}
```

Deleting a [product](#products--delete) deletes all its media.

<a id="product-media--errors"></a>

### Error Handling

Source: https://www.achieveapex.com/docs/api-reference/product-media/errors

The Product Media API returns standard HTTP status codes and error messages.

#### Error Response

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

#### Status Codes

| Status Code | Description |
|-------------|-------------|
| `400 Bad Request` | Invalid parameters or request |
| `401 Unauthorized` | Missing or invalid authentication |
| `403 Forbidden` | Not authorized to access this organization's product media |
| `404 Not Found` | Product media item not found, or the path `/product-media` was used instead of `/products-media` |
| `500 Internal Server Error` | Server error |

---

## Products

<a id="products"></a>

### Products overview

Source: https://www.achieveapex.com/docs/api-reference/products

Products and services in your organization's catalog. Use them in deals, orders, invoices, the public catalog and AI assistant product search.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/products` | [List products](#products--list) |
| `GET` | `/products/:id` | [Get a product](#products--get) |
| `POST` | `/products` | [Create a product](#products--create) |
| `PATCH` | `/products/:id` | [Update a product](#products--update) |
| `DELETE` | `/products/:id` | [Delete a product](#products--delete) |

All requests use your API key in the `x-api-key` header. The key is scoped to one organization: reads only return that organization's products, and `organization_id` is required in the body when you create a product.

#### The product object

```json
{
  "id": 123,
  "organization_id": 27,
  "name": "Premium Subscription",
  "description": "Annual premium subscription with all features included",
  "type": "service",
  "status": "active",
  "price": "999.99",
  "system_currency_id": 2,
  "sku": "PREM-SUB-12M",
  "product_category_id": 5,
  "parent_id": null,
  "is_variant": false,
  "track_inventory": false,
  "allow_backorder": false,
  "stock_quantity": null,
  "billing_type": "recurring",
  "billing_interval": "year",
  "billing_interval_count": 1,
  "meta_data": null,
  "is_embeddable": true,
  "custom_fields_by_key": { "brand": "Apex" },
  "custom_fields_by_name": { "Brand": "Apex" },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 41,
      "custom_field_key": "brand",
      "custom_field_name": "Brand",
      "custom_field_value": "Apex",
      "last_updated": "2026-03-15T10:45:20.391Z"
    }
  ],
  "created_at": "2026-03-15T10:45:20.391Z",
  "updated_at": "2026-03-15T10:45:20.391Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the product. Required on create; cannot be changed. |
| `name` | string | Product name (up to 255 characters). Required. |
| `description` | string \| null | Free-text description. |
| `type` | string | One of `product`, `service`. Required. |
| `status` | string | One of `active`, `inactive`. Default `active`. |
| `price` | number | Base price, `0` or more, with 2 decimals. Default `0`. Responses return it as a decimal string (for example `"999.99"`). |
| `system_currency_id` | integer \| null | Currency of `price` (ID of a system currency). `null` uses the organization's default currency. |
| `sku` | string \| null | Stock keeping unit (up to 255 characters). Must be unique among the organization's non-deleted products. |
| `product_category_id` | integer \| null | ID of a [product category](#product-categories) of the same organization. |
| `parent_id` | integer \| null | Parent product ID, for variants. |
| `is_variant` | boolean | Whether this product is a variant of `parent_id`. Default `false`. |
| `track_inventory` | boolean | When `true`, orders deduct `stock_quantity` and the catalog checkout checks availability. Default `false`. |
| `allow_backorder` | boolean | With `track_inventory`, allows selling when `stock_quantity` is not enough. Default `false`. |
| `stock_quantity` | number \| null | Units in stock, `0` or more. |
| `billing_type` | string | One of `one_time`, `recurring`. Default `one_time`. |
| `billing_interval` | string \| null | For `recurring`: one of `day`, `week`, `month`, `quarter`, `year`, `custom`. Defaults to `month` for recurring products; always `null` for `one_time`. |
| `billing_interval_count` | number \| null | For `recurring`: number of intervals per billing cycle (at least `1`, default `1`). Always `null` for `one_time`. |
| `meta_data` | object \| null | Free-form JSON stored with the product. |
| `is_embeddable` | boolean | When `true`, the product is indexed for AI assistant product search. Setting it to `false` removes it from the index. Default `false`. |
| `custom_fields_by_key` | object | Product custom field values keyed by the field `key` (see `GET /custom-fields?entity_type=product`). Write custom fields with this object. |
| `custom_fields_by_name` | object | Read-only. Same values keyed by the field name. Rebuilt by the API. |
| `custom_fields_meta_data` | array | Read-only. One item per custom field value: `custom_field_id`, `custom_field_key`, `custom_field_name`, `custom_field_value`, `last_updated`. Rebuilt by the API. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the product is deleted. |

#### Related

- [Product categories](#product-categories)
- [Product media](#product-media)
- [Deal products](#deal-products)

<a id="products--list"></a>

### List products

Source: https://www.achieveapex.com/docs/api-reference/products/list

Retrieve your organization's products, with filters, text search and pagination.

#### Endpoint

`GET /products`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `searchTerm` | string | No | Case- and accent-insensitive search on `name`, `description` and `sku`. Exact and prefix name matches come first. |
| `product_category_id` | integer | No | Only products of this category. |
| `status` | string | No | `active` or `inactive`. |
| `type` | string | No | `product` or `service`. |
| `sku` | string | No | Exact SKU. |
| `parent_id` | integer | No | Only variants of this product. |
| `is_variant` | boolean | No | `true` for variants only, `false` for base products only. |
| `price` | number | No | Exact price, or a range with `price[$gte]=100&price[$lte]=1000`. |
| `fastJoinForProductList` | boolean | No | Send `true` to add `category` (`id`, `name`, `organization_id`) and `main_media_path` (the `file_path` of the first media item by `position`) to each product. Omit it otherwise. |
| `$limit` | integer | No | Page size (default 10, max 50). |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, for example `$sort[name]=1`. With `searchTerm`, only `name`, `created_at`, `updated_at`, `price`, `sku` and `id` are used, after the relevance order. |
| `$select[]` | string | No | Return only these fields. |

Any other product field can be used as a filter with Feathers syntax (`field=value`, `field[$in][]=a`, `field[$gt]=x`). Results are filtered to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/products \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'status=active' \
  --data-urlencode 'fastJoinForProductList=true' \
  --data-urlencode '$limit=10' \
  --data-urlencode '$sort[name]=1'
```

Search by text:

```bash
curl -G https://integrations.achieveapex.com/products \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'searchTerm=premium' \
  --data-urlencode '$limit=10'
```

#### Response

```json
{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "organization_id": 27,
      "name": "Premium Subscription",
      "description": "Annual premium subscription with all features included",
      "type": "service",
      "status": "active",
      "price": "999.99",
      "system_currency_id": 2,
      "sku": "PREM-SUB-12M",
      "product_category_id": 5,
      "parent_id": null,
      "is_variant": false,
      "track_inventory": false,
      "allow_backorder": false,
      "stock_quantity": null,
      "billing_type": "recurring",
      "billing_interval": "year",
      "billing_interval_count": 1,
      "meta_data": null,
      "is_embeddable": true,
      "custom_fields_by_key": { "brand": "Apex" },
      "custom_fields_by_name": { "Brand": "Apex" },
      "custom_fields_meta_data": [],
      "created_at": "2026-03-15T10:45:20.391Z",
      "updated_at": "2026-03-15T10:45:20.391Z",
      "deleted_at": null,
      "category": { "id": 5, "name": "Subscriptions", "organization_id": 27 },
      "main_media_path": "org_27/products/product_123/product-media_20260315T104520_front.jpg"
    }
  ]
}
```

`category` and `main_media_path` are only present when `fastJoinForProductList=true`.

<a id="products--get"></a>

### Get a product

Source: https://www.achieveapex.com/docs/api-reference/products/get

Retrieve one product by ID.

#### Endpoint

`GET /products/:id`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `fastJoinForProductList` | boolean | No | Send `true` to add `category` and `main_media_path`, as in [List products](#products--list). |

#### Request

```bash
curl https://integrations.achieveapex.com/products/123 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 123,
  "organization_id": 27,
  "name": "Premium Subscription",
  "description": "Annual premium subscription with all features included",
  "type": "service",
  "status": "active",
  "price": "999.99",
  "system_currency_id": 2,
  "sku": "PREM-SUB-12M",
  "product_category_id": 5,
  "parent_id": null,
  "is_variant": false,
  "track_inventory": false,
  "allow_backorder": false,
  "stock_quantity": null,
  "billing_type": "recurring",
  "billing_interval": "year",
  "billing_interval_count": 1,
  "meta_data": null,
  "is_embeddable": true,
  "custom_fields_by_key": { "brand": "Apex" },
  "custom_fields_by_name": { "Brand": "Apex" },
  "custom_fields_meta_data": [],
  "created_at": "2026-03-15T10:45:20.391Z",
  "updated_at": "2026-03-15T10:45:20.391Z",
  "deleted_at": null
}
```

The media of a product are listed with [`GET /products-media?product_id=123`](#product-media--list).

#### Errors

| Status | Cause |
|---|---|
| `404 Not Found` | No product with this ID in your organization, or it was deleted. |

<a id="products--create"></a>

### Create a product

Source: https://www.achieveapex.com/docs/api-reference/products/create

Add a product or service to your organization's catalog.

#### Endpoint

`POST /products`

#### Body parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `name` | string | Yes | Product name (up to 255 characters). |
| `type` | string | Yes | `product` or `service`. |
| `description` | string \| null | No | Description. |
| `status` | string | No | `active` (default) or `inactive`. |
| `price` | number | No | Base price, `0` or more. Default `0`. |
| `system_currency_id` | integer \| null | No | Currency of `price`. |
| `sku` | string \| null | No | Must be unique among your organization's products. |
| `product_category_id` | integer \| null | No | ID of an existing [product category](#product-categories) of your organization. |
| `parent_id` | integer \| null | No | Parent product, for variants. |
| `is_variant` | boolean | No | Default `false`. |
| `track_inventory` | boolean | No | Deduct `stock_quantity` on orders. Default `false`. |
| `allow_backorder` | boolean | No | Allow selling beyond stock when tracking inventory. Default `false`. |
| `stock_quantity` | number \| null | No | Units in stock, `0` or more. |
| `billing_type` | string | No | `one_time` (default) or `recurring`. |
| `billing_interval` | string \| null | No | For `recurring`: `day`, `week`, `month` (default), `quarter`, `year` or `custom`. Ignored for `one_time`. |
| `billing_interval_count` | number \| null | No | For `recurring`: intervals per cycle, at least `1` (default `1`). Ignored for `one_time`. |
| `meta_data` | object \| null | No | Free-form JSON. |
| `is_embeddable` | boolean | No | `true` indexes the product for AI assistant product search. Default `false`. |
| `custom_fields_by_key` | object | No | Custom field values keyed by field `key` from `GET /custom-fields?entity_type=product`. |

See the [product object](#products) for every field.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/products \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "name": "Basic Subscription",
    "description": "Annual basic subscription for small teams",
    "type": "service",
    "price": 299.99,
    "sku": "BASIC-SUB-12M",
    "billing_type": "recurring",
    "billing_interval": "year",
    "billing_interval_count": 1,
    "custom_fields_by_key": { "brand": "Apex" }
  }'
```

#### Response

```json
{
  "id": 126,
  "organization_id": 27,
  "name": "Basic Subscription",
  "description": "Annual basic subscription for small teams",
  "type": "service",
  "status": "active",
  "price": "299.99",
  "system_currency_id": null,
  "sku": "BASIC-SUB-12M",
  "product_category_id": null,
  "parent_id": null,
  "is_variant": false,
  "track_inventory": false,
  "allow_backorder": false,
  "stock_quantity": null,
  "billing_type": "recurring",
  "billing_interval": "year",
  "billing_interval_count": 1,
  "meta_data": null,
  "is_embeddable": false,
  "custom_fields_by_key": { "brand": "Apex" },
  "custom_fields_by_name": { "Brand": "Apex" },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 41,
      "custom_field_key": "brand",
      "custom_field_name": "Brand",
      "custom_field_value": "Apex",
      "last_updated": "2026-05-11T16:26:32.160Z"
    }
  ],
  "created_at": "2026-05-11T16:26:32.164Z",
  "updated_at": "2026-05-11T16:26:32.160Z",
  "deleted_at": null
}
```

#### Errors

| Status | Message / cause |
|---|---|
| `400 Bad Request` | `A product with SKU '…' already exists in your organization. Please use a different SKU.` |
| `400 Bad Request` | Schema validation failed (missing `name`, `type` or `organization_id`, unknown field, wrong type or enum value). |
| `403 Forbidden` | `organization_id` is missing or is not the API key's organization. |

<a id="products--update"></a>

### Update a product

Source: https://www.achieveapex.com/docs/api-reference/products/update

Change some fields of a product (partial update).

#### Endpoint

`PATCH /products/:id`

#### Body parameters

Any writable field of the [product object](#products): `name`, `description`, `type`, `status`, `price`, `system_currency_id`, `sku`, `product_category_id`, `parent_id`, `is_variant`, `track_inventory`, `allow_backorder`, `stock_quantity`, `billing_type`, `billing_interval`, `billing_interval_count`, `meta_data`, `is_embeddable`, `custom_fields_by_key`. Only the fields you send change. `organization_id` cannot be changed.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/products/126 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic Subscription Plus",
    "price": 349.99,
    "billing_type": "recurring",
    "billing_interval": "year",
    "billing_interval_count": 1,
    "custom_fields_by_key": { "brand": "Apex" }
  }'
```

#### Response

Returns the updated [product](#products).

```json
{
  "id": 126,
  "organization_id": 27,
  "name": "Basic Subscription Plus",
  "description": "Annual basic subscription for small teams",
  "type": "service",
  "status": "active",
  "price": "349.99",
  "system_currency_id": null,
  "sku": "BASIC-SUB-12M",
  "product_category_id": null,
  "parent_id": null,
  "is_variant": false,
  "track_inventory": false,
  "allow_backorder": false,
  "stock_quantity": null,
  "billing_type": "recurring",
  "billing_interval": "year",
  "billing_interval_count": 1,
  "meta_data": null,
  "is_embeddable": false,
  "custom_fields_by_key": { "brand": "Apex" },
  "custom_fields_by_name": { "Brand": "Apex" },
  "custom_fields_meta_data": [],
  "created_at": "2026-05-11T16:26:32.164Z",
  "updated_at": "2026-05-12T09:02:10.512Z",
  "deleted_at": null
}
```

#### Notes

- **Billing cadence:** every `PATCH` normalizes `billing_type`. A request without `billing_type` sets it to `one_time` and clears `billing_interval` and `billing_interval_count`. When you update a recurring product, always send `billing_type`, `billing_interval` and `billing_interval_count` with the other fields.
- **Custom fields:** send `custom_fields_by_key` with field keys from `GET /custom-fields?entity_type=product`. Setting a key to `null` clears it. The API rebuilds `custom_fields_by_name` and `custom_fields_meta_data`.
- **AI search:** `is_embeddable: true` (re)indexes the product for AI assistant product search, `false` removes it. Changing custom fields of an embeddable product re-indexes it.

#### Errors

| Status | Message / cause |
|---|---|
| `400 Bad Request` | `A product with SKU '…' already exists in your organization. Please use a different SKU.` |
| `404 Not Found` | No product with this ID in your organization. |

<a id="products--delete"></a>

### Delete a product

Source: https://www.achieveapex.com/docs/api-reference/products/delete

Delete a product. This is a soft delete: the product gets `deleted_at` and no longer appears in list or get.

#### Endpoint

`DELETE /products/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/products/126 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [product](#products) with `deleted_at` set.

```json
{
  "id": 126,
  "organization_id": 27,
  "name": "Basic Subscription Plus",
  "type": "service",
  "status": "active",
  "price": "349.99",
  "sku": "BASIC-SUB-12M",
  "created_at": "2026-05-11T16:26:32.164Z",
  "updated_at": "2026-05-12T10:15:00.000Z",
  "deleted_at": "2026-05-12T10:15:00.000Z"
}
```

(Shortened: the response contains every field of the product object.)

#### Side effects

- The product's [media](#product-media) records are deleted too, and their files are removed from storage.
- The product is removed from AI assistant product search.
- Deals, orders and invoices that already reference the product keep their line items. Variants (`parent_id` = this product) are not deleted.

<a id="products--errors"></a>

### Error Handling

Source: https://www.achieveapex.com/docs/api-reference/products/errors

The Products API returns standard HTTP status codes and error messages.

#### Error Response

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

#### Status Codes

| Status Code | Description |
|-------------|-------------|
| `400 Bad Request` | Invalid parameters or request |
| `401 Unauthorized` | Missing or invalid authentication |
| `403 Forbidden` | Not authorized to access this organization's products |
| `404 Not Found` | Product not found |
| `500 Internal Server Error` | Server error |

---

## Reservation available slots

<a id="reservation-available-slots"></a>

### Reservation available slots overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-available-slots

Computes the bookable time slots of a [service](#reservation-services) on one date. Use it before [creating a reservation](#reservations--create): send the chosen slot's `start_datetime`. It is read-only and calculated on every request; nothing is stored.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-available-slots` | [Get available slots](#reservation-available-slots--list) |

#### The availability object

```json
{
  "available": true,
  "date": "2026-04-25",
  "service_id": 12,
  "resource_id": 88,
  "duration_minutes": 60,
  "max_party_size": 8,
  "slot_capacity": 4,
  "timezone": "America/New_York",
  "slots": [
    {
      "time": "09:00",
      "start_datetime": "2026-04-25T09:00:00.000Z",
      "end_datetime": "2026-04-25T10:00:00.000Z",
      "available": true,
      "available_spots": 3,
      "total_capacity": 4,
      "booked": 1
    }
  ]
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `available` | boolean | `true` when at least one slot can be booked. |
| `reason` | string | Only when the whole day is unavailable. One of `Service is not active`, `Cannot book past dates`, `Cannot book more than N days in advance`, `No availability configured for this day`, `This date is blocked`, `All resources are blocked on this date`. |
| `date` | string | Requested date, `YYYY-MM-DD`. Absent when `reason` is returned. |
| `service_id` | integer | Requested service. Absent when `reason` is returned. |
| `resource_id` | integer | Requested resource, only when `resource_id` was sent. |
| `duration_minutes` | integer | Service duration. |
| `max_party_size` | integer | Service maximum party size. |
| `slot_capacity` | integer | Reservations allowed per slot. |
| `timezone` | string | Service timezone. Slot times are wall-clock times in this zone. |
| `slots` | array | Slots of the day in time order (empty when `reason` is returned). |
| `slots[].time` | string | Start time, `HH:mm`. |
| `slots[].start_datetime` | string | Start, in the format expected by `POST /reservations` (wall-clock time with `Z` suffix, not UTC). |
| `slots[].end_datetime` | string | Start + `duration_minutes`. |
| `slots[].available` | boolean | `true` when `available_spots` ≥ 1. Full slots are still listed with `false`. |
| `slots[].available_spots` | integer | `slot_capacity` minus `booked`, never below 0. |
| `slots[].total_capacity` | integer | Same as `slot_capacity`. |
| `slots[].booked` | integer | Capacity already used in the slot (reservations, or people when `capacity_unit` is `people`). |
| `slots[].start_time`, `slots[].end_time` | string | Start and end, `HH:mm`. |
| `slots[].remaining_capacity` | integer | Capacity still free in the slot: bookings, or seats when the service `capacity_unit` is `people`. |
| `slots[].available_resource_ids` | array of integers | Resources free for the whole slot. |
| `slots[].unavailable_reason` | string | Only on unavailable slots: `full`, `resource_unavailable`, `calendar_busy`, `calendar_error` or `outside_hours`. |
| `duration_mode`, `duration_options`, `capacity_unit`, `min_party_size`, `party_size` | | The service settings used and the requested party size. |
| `calendar_errors` | array | Connected calendars that could not be read. Their slots are not offered until the calendar works again. Each item: `link_id`, `scope`, `service_id`, `resource_id`, `source_type`, `calendar_integration_id`, `label`, `message`. |

#### How slots are calculated

1. **Hours.** If the service has no [linked resources](#reservation-service-resources), the day runs 08:00–18:00. Otherwise each linked resource's active [weekly blocks](#reservation-resource-availability) for that weekday are used (only `resource_id`'s when it is sent).
2. **Exceptions.** An organization-wide `blocked` [exception](#reservation-resource-exceptions) closes the day; a resource `blocked` exception removes that resource's hours; a resource `special_hours` exception replaces them with its `start_time`–`end_time`.
3. **Slots.** Starting at each block's start, a slot every `slot_interval` minutes while start + `duration_minutes` fits before the block end. Duplicate start times across resources are merged.
4. **Booking window.** Slots starting before now + `min_advance_hours` or after `max_advance_days` (service timezone) are dropped. `buffer_before_minutes` / `buffer_after_minutes` must also be free.
5. **Occupancy.** Overlapping `pending`, `confirmed` and unexpired `awaiting_payment` reservations count against `slot_capacity` (one each, or their `party_size` when `capacity_unit` is `people`) and against each resource's `capacity`. A resource is busy when a reservation of any service assigned to it overlaps. `max_daily_bookings` closes the day when reached.
6. **Connected calendars.** Busy time of calendars linked to the organization, the service or a resource (Google, Outlook, or open CRM activities of a member) removes the slots it overlaps. A calendar that cannot be read blocks its slots and is listed in `calendar_errors`.

Weekly availability `breaks` and `valid_from`/`valid_until` are honored. [Creating a reservation](#reservations--create) runs the same checks again at booking time, so a slot taken in between is rejected with `400`.

#### Related

- [Reservations](#reservations)
- [Reservation services](#reservation-services)
- [Reservation resource availability](#reservation-resource-availability)

<a id="reservation-available-slots--list"></a>

### Get available slots

Source: https://www.achieveapex.com/docs/api-reference/reservation-available-slots/list

Returns the slots of one service on one date. The response is a single object, not a paginated list.

#### Endpoint

`GET /reservation-available-slots`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. |
| `service_id` | integer | Yes | [Service](#reservation-services) to check. |
| `date` | string (`YYYY-MM-DD`) | Yes | Date in the service's timezone. |
| `resource_id` | integer | No | Only this resource's hours and bookings. Use it to offer a specific staff member or room (send it as `preferred_resource_id` when creating the reservation). |
| `duration_minutes` | integer | No | For services with `duration_mode: "flexible"`: the length to check, one of the service `duration_options`. |
| `party_size` | integer | No | Default `1`. With `capacity_unit: "people"` a slot is available only when this many seats are free. Outside the service `min_party_size`–`max_party_size` no slots are returned. |
| `exclude_reservation_id` | integer | No | Ignore this reservation when counting bookings (to offer new times when rescheduling it). |
| `live` | boolean | No | `true` reads connected calendars without the 2-minute cache. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservation-available-slots \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'service_id=12' \
  --data-urlencode 'date=2026-04-25'
```

#### Response

```json
{
  "available": true,
  "date": "2026-04-25",
  "service_id": 12,
  "duration_minutes": 60,
  "max_party_size": 8,
  "slot_capacity": 4,
  "timezone": "America/New_York",
  "slots": [
    {
      "time": "09:00",
      "start_datetime": "2026-04-25T09:00:00.000Z",
      "end_datetime": "2026-04-25T10:00:00.000Z",
      "available": true,
      "available_spots": 3,
      "total_capacity": 4,
      "booked": 1
    },
    {
      "time": "09:30",
      "start_datetime": "2026-04-25T09:30:00.000Z",
      "end_datetime": "2026-04-25T10:30:00.000Z",
      "available": false,
      "available_spots": 0,
      "total_capacity": 4,
      "booked": 4
    }
  ]
}
```

When the whole day is unavailable:

```json
{
  "available": false,
  "reason": "This date is blocked",
  "slots": [],
  "timezone": "America/New_York"
}
```

See [how slots are calculated](#reservation-available-slots) for every field and reason.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `service_id`, `date` or `organization_id` is missing. |
| `404 Not Found` | The service does not exist. |

---

## Reservation booking links

<a id="reservation-booking-links"></a>

### Reservation booking links overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-booking-links

A booking link is a public page where customers book your [reservation services](#reservation-services) themselves. Each link has a `slug`, a `mode` that decides which services it shows, and a `page_config` with its branding, texts and form. The page is served at `/b/{organization_id}/{slug}` on the AchieveApex web app, and bookings made there are created as [reservations](#reservations).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-booking-links` | [List booking links](#reservation-booking-links--list) |
| `GET` | `/reservation-booking-links/:id` | [Get a booking link](#reservation-booking-links--get) |
| `POST` | `/reservation-booking-links` | [Create a booking link](#reservation-booking-links--create) |
| `PATCH` | `/reservation-booking-links/:id` | [Update a booking link](#reservation-booking-links--update) |
| `DELETE` | `/reservation-booking-links/:id` | [Delete a booking link](#reservation-booking-links--delete) |

#### The booking link object

```json
{
  "id": 301,
  "organization_id": 456,
  "name": "Main booking page",
  "slug": "book",
  "mode": "selected_services",
  "service_id": null,
  "is_active": true,
  "page_config": {
    "hero_title": "Book your visit",
    "primary_color": "#2563EB",
    "booking_service_ids": [12, 14],
    "booking_contact_identify_mode": "email_first",
    "thank_you_message": "Thanks! We will see you soon."
  },
  "settings": {},
  "tracking_config": {
    "meta_pixel_id": "123456789012345",
    "ga4_measurement_id": "G-ABC123XYZ"
  },
  "created_by_user_id": 789,
  "created_at": "2026-04-17T12:00:00.000Z",
  "updated_at": "2026-04-18T09:30:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Owning organization. Required on create; must be the API key's organization. |
| `name` | string | Internal name, max 255 characters. Required on create. |
| `slug` | string | URL segment of the public page. 3–64 characters: lowercase letters, numbers and dashes, starting with a letter or number (spaces become dashes, upper case is lowered). Unique per organization (including deleted links). Generated from `name` plus a random suffix when omitted on create. |
| `mode` | string | Which services the page shows: `all_services` (default), `single_service` or `selected_services`. See below. |
| `service_id` | integer \| null | The service for `single_service` (required in that mode). Forced to `null` in the other modes. |
| `is_active` | boolean | Default `true`. Inactive links return "not active" on the public page. |
| `page_config` | object | Branding, texts, contact form and service layout. Default `{}`. See the reference below. Replaced as a whole on update. |
| `settings` | object | Free-form object stored with the link. Default `{}`. Not used by the public page. |
| `tracking_config` | object | Default `{}`. Analytics on the public page: `meta_pixel_id` (digits only, 5–20) and `ga4_measurement_id` (`G-XXXXXXXXXX`). Invalid IDs return `400`. `custom_head_code` / `custom_body_code` are accepted by the schema but removed on save: booking pages never run custom code. |
| `created_by_user_id` | integer \| null | Read-only. User who created the link; with an API key, the user the key belongs to. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the link is deleted. |

##### `mode`

| Value | Services shown |
|---|---|
| `all_services` | Every service with `is_active: true` and `is_public: true`. Order and group them with `page_config.booking_all_services_order` / `booking_all_services_sections`. |
| `single_service` | Only `service_id`. |
| `selected_services` | The services in `page_config.booking_service_sections` (grouped) or `page_config.booking_service_ids`. At least one is required, and all must belong to your organization. |

Inactive or non-public services never appear, whatever the mode.

#### `page_config` reference

`page_config` is a free-form object used by the public booking page. All keys are optional. Colors are CSS hex strings (e.g. `#2563EB`). The server validates `video_url` and the service-selection keys; the rest is stored as sent.

##### Content and copy

| Key | Type | Description |
|-----|------|-------------|
| `hero_title` | String | Hero title override. |
| `show_hero_title` | Boolean | Default true if omitted. |
| `hero_fallback_to_link_name` | Boolean | Use link name when hero title empty. |
| `hero_subtitle` | String | |
| `description` | String | Body/description. |
| `instructions` | String | Instructions shown on the flow. |
| `thank_you_message` | String | Post-booking message. |
| `policy_text` | String | Policy / legal footer. |
| `booking_page_copy` | Object | Partial string overrides for UI labels (see app `BookingPageCopy`). |
| `booking_page_copy_preset` | String | `english` or `spanish` presets in the UI. |

##### Media and layout

| Key | Type | Description |
|-----|------|-------------|
| `logo_url` | String | Logo image URL. |
| `cover_image_url` | String | Hero cover image URL. |
| `video_url` | String | Intro video shown on the page (YouTube, Vimeo, Loom, Wistia, Google Drive, `<iframe>` embed code, direct video URL…). Unsupported links return `400`. |
| `video_title` | String | Title above the video, trimmed to 200 characters. |
| `booking_logo_placement` | String | e.g. `below_cover`. |
| `booking_logo_shape` | String | e.g. `rounded`. |
| `booking_logo_size` | String | e.g. `md`. |
| `booking_logo_background_color` | String | |
| `booking_logo_border_color` | String | |
| `booking_logo_border_width_px` | Number | |
| `booking_logo_show_shadow` | Boolean | |
| `booking_logo_show_ring` | Boolean | |
| `booking_logo_ring_color` | String | |
| `booking_logo_ring_width_px` | Number | |

##### Theme and colors

| Key | Type | Description |
|-----|------|-------------|
| `booking_page_theme` | String | `custom` or preset mode from theme picker. |
| `primary_color` | String | |
| `background_color` | String | |
| `text_color` | String | |
| `heading_color` | String | |
| `muted_text_color` | String | |
| `link_color` | String | |
| `on_primary_color` | String | |
| `surface_color` | String | |
| `surface_border_color` | String | |
| `input_background_color` | String | |
| `input_border_color` | String | |
| `hero_title_text_color` | String | |
| `hero_subtitle_text_color` | String | |
| `service_icon_text_color` | String | |
| `summary_banner_color` | String | |
| `instruction_banner_color` | String | |
| `instruction_banner_text_color` | String | |
| `empty_state_background_color` | String | |
| `empty_state_border_color` | String | |
| `empty_state_text_color` | String | |
| `slot_button_background_color` | String | |
| `slot_button_idle_text_color` | String | |
| `stepper_inactive_color` | String | |
| `stepper_connector_color` | String | |
| `stepper_text_color` | String | |
| `service_list_background_color` | String | |
| `service_list_border_color` | String | |
| `service_list_heading_text_color` | String | |
| `service_list_primary_text_color` | String | |
| `service_list_secondary_text_color` | String | |
| `calendar_panel_background_color` | String | |
| `calendar_panel_border_color` | String | |
| `calendar_section_heading_text_color` | String | |
| `calendar_panel_text_color` | String | |
| `times_panel_background_color` | String | |
| `times_panel_border_color` | String | |
| `times_section_heading_text_color` | String | |
| `times_panel_secondary_text_color` | String | |
| `times_panel_text_color` | String | |
| `details_section_heading_text_color` | String | |
| `customer_details_text_color` | String | |
| `confirmation_title_text_color` | String | |
| `confirmation_body_text_color` | String | |
| `confirmation_recap_text_color` | String | |
| `policy_footer_text_color` | String | |
| `summary_strip_primary_text_color` | String | |
| `summary_strip_secondary_text_color` | String | |

##### Service list presentation

| Key | Type | Description |
|-----|------|-------------|
| `service_list_thumbnail_mode` | String | `color`, `image`, `letter`, or `none`. |
| `service_list_layout` | String | `list` or `grid`. |
| `show_service_description` | Boolean | Default true if omitted. |
| `show_powered_by` | Boolean | |

##### Contact form

| Key | Type | Description |
|-----|------|-------------|
| `booking_contact_fields` | Object | Flags for `first_name`, `last_name`, `email`, `phone`, `party_size`, `notes`. |
| `booking_contact_identify_mode` | String | `email_first` or `phone_first`. |
| `booking_identify_show_heading` | Boolean | |
| `booking_identify_show_helper` | Boolean | |
| `booking_default_phone_country_iso` | String | e.g. `US`. |
| `booking_default_phone_country_code` | String | e.g. `+1`. |
| `booking_default_party_size` | Number | |
| `booking_contact_custom_field_ids` | Number[] | Contact custom field IDs to show. |
| `booking_reservation_custom_field_ids` | Number[] | Reservation custom field IDs to show. |

##### Service selection (mode-dependent)

| Key | Type | Description |
|-----|------|-------------|
| `booking_service_ids` | Number[] | Services shown with `selected_services` when no sections are set. |
| `booking_service_sections` | Array | `{ id, title, service_ids: number[] }` groups for `selected_services`. When present, takes precedence over `booking_service_ids`. |
| `booking_all_services_order` | Number[] | Optional order for `all_services`. |
| `booking_all_services_sections` | Array | Same section shape for all-services mode. |

Upload a logo, cover or video file with `POST /s3-url-signing` (types `booking-link-logo`, `booking-link-cover`, `meeting-booking-video`), `PUT` the file to the signed URL, then store the URL in `page_config`.

#### Related

- [Reservation services](#reservation-services)
- [Reservations](#reservations)

<a id="reservation-booking-links--list"></a>

### List reservation booking links

Source: https://www.achieveapex.com/docs/api-reference/reservation-booking-links/list

Returns a paginated list of the organization's booking links.

#### Endpoint

`GET /reservation-booking-links`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `is_active` | boolean | No | Only active or inactive links. |
| `mode` | string | No | `all_services`, `single_service` or `selected_services`. |
| `service_id` | integer | No | `single_service` links of this service. |
| `slug` | string | No | The link with this slug. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. |
| `$select[]` | string | No | Return only these fields (for example to skip the large `page_config`). |

Results are limited to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservation-booking-links \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'is_active=true' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[name]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 301,
      "organization_id": 456,
      "name": "Main booking page",
      "slug": "book",
      "mode": "all_services",
      "service_id": null,
      "is_active": true,
      "page_config": { "primary_color": "#2563EB", "hero_title": "Book your visit" },
      "settings": {},
      "tracking_config": { "meta_pixel_id": null, "ga4_measurement_id": null },
      "created_by_user_id": 789,
      "created_at": "2026-04-17T12:00:00.000Z",
      "updated_at": "2026-04-18T09:30:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="reservation-booking-links--get"></a>

### Get a reservation booking link

Source: https://www.achieveapex.com/docs/api-reference/reservation-booking-links/get

Returns one booking link by ID, including its full `page_config`.

#### Endpoint

`GET /reservation-booking-links/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservation-booking-links/301 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 301,
  "organization_id": 456,
  "name": "Main booking page",
  "slug": "book",
  "mode": "selected_services",
  "service_id": null,
  "is_active": true,
  "page_config": {
    "hero_title": "Book your visit",
    "primary_color": "#2563EB",
    "booking_service_ids": [12, 14],
    "thank_you_message": "Thanks! We will see you soon."
  },
  "settings": {},
  "tracking_config": { "meta_pixel_id": "123456789012345", "ga4_measurement_id": null },
  "created_by_user_id": 789,
  "created_at": "2026-04-17T12:00:00.000Z",
  "updated_at": "2026-04-18T09:30:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No booking link with that ID in your organization, or it was deleted. |

<a id="reservation-booking-links--create"></a>

### Create a reservation booking link

Source: https://www.achieveapex.com/docs/api-reference/reservation-booking-links/create

Creates a public booking page. It is live at `/b/{organization_id}/{slug}` on the AchieveApex web app as soon as it is created with `is_active: true`.

#### Endpoint

`POST /reservation-booking-links`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `name` | string | Yes | Internal name. |
| `mode` | string | Yes | `all_services`, `single_service` or `selected_services`. |
| `service_id` | integer | When `mode` is `single_service` | The service to book. Must belong to your organization. |
| `slug` | string | No | URL segment, unique per organization. Generated from `name` when omitted. |
| `is_active` | boolean | No | Default `true`. |
| `page_config` | object | When `mode` is `selected_services` | Must contain `booking_service_ids` or `booking_service_sections` in that mode. See the [`page_config` reference](#reservation-booking-links). |
| `settings` | object | No | Free-form object. Default `{}`. |
| `tracking_config` | object | No | `meta_pixel_id`, `ga4_measurement_id`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/reservation-booking-links \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Consultations",
    "slug": "consult",
    "mode": "single_service",
    "service_id": 12,
    "page_config": {
      "hero_title": "Book a consultation",
      "primary_color": "#2563EB",
      "booking_contact_identify_mode": "email_first",
      "booking_default_party_size": 1
    }
  }'
```

#### Response

Returns the created [booking link object](#reservation-booking-links).

```json
{
  "id": 302,
  "organization_id": 456,
  "name": "Consultations",
  "slug": "consult",
  "mode": "single_service",
  "service_id": 12,
  "is_active": true,
  "page_config": {
    "hero_title": "Book a consultation",
    "primary_color": "#2563EB",
    "booking_contact_identify_mode": "email_first",
    "booking_default_party_size": 1
  },
  "settings": {},
  "tracking_config": {},
  "created_by_user_id": 789,
  "created_at": "2026-04-17T12:00:00.000Z",
  "updated_at": "2026-04-17T12:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field; invalid `mode`; `service_id` missing for `single_service`; no services in `page_config` for `selected_services`; a service of another organization; invalid or already used `slug`; unsupported `page_config.video_url`; invalid tracking ID. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservation-booking-links--update"></a>

### Update a reservation booking link

Source: https://www.achieveapex.com/docs/api-reference/reservation-booking-links/update

Partially updates a booking link. Only the top-level fields you send change, but `page_config`, `settings` and `tracking_config` are each **replaced as a whole**: [get the link](#reservation-booking-links--get), change the keys you need and send the complete object.

#### Endpoint

`PATCH /reservation-booking-links/:id`

#### Body

Any field of the [booking link object](#reservation-booking-links) except `id`. The same rules as on create apply: switching to `single_service` needs a `service_id`, switching to `selected_services` needs services in `page_config`, and switching to `all_services` or `selected_services` sets `service_id` to `null`. A new `slug` must be unique in your organization; changing it changes the public URL.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-booking-links/301 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'
```

Change the page texts (send the whole `page_config`):

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-booking-links/301 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_config": {
      "hero_title": "Book your visit",
      "primary_color": "#1D4ED8",
      "booking_service_ids": [12, 14],
      "thank_you_message": "Thank you for booking with us."
    }
  }'
```

#### Response

Returns the updated [booking link object](#reservation-booking-links).

```json
{
  "id": 301,
  "organization_id": 456,
  "name": "Main booking page",
  "slug": "book",
  "mode": "selected_services",
  "service_id": null,
  "is_active": true,
  "page_config": {
    "hero_title": "Book your visit",
    "primary_color": "#1D4ED8",
    "booking_service_ids": [12, 14],
    "thank_you_message": "Thank you for booking with us."
  },
  "settings": {},
  "tracking_config": { "meta_pixel_id": "123456789012345", "ga4_measurement_id": null },
  "created_by_user_id": 789,
  "created_at": "2026-04-17T12:00:00.000Z",
  "updated_at": "2026-04-18T09:30:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Same validation as [create](#reservation-booking-links--create). |
| `404 Not Found` | No booking link with that ID in your organization. |

<a id="reservation-booking-links--delete"></a>

### Delete a reservation booking link

Source: https://www.achieveapex.com/docs/api-reference/reservation-booking-links/delete

Deletes a booking link; its public page stops working. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get. Its slug cannot be reused by another link of the organization. To take the page offline temporarily, [update](#reservation-booking-links--update) it with `is_active: false` instead.

#### Endpoint

`DELETE /reservation-booking-links/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservation-booking-links/301 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [booking link object](#reservation-booking-links) with `deleted_at` set.

```json
{
  "id": 301,
  "organization_id": 456,
  "name": "Main booking page",
  "slug": "book",
  "mode": "all_services",
  "is_active": true,
  "deleted_at": "2026-04-22T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No booking link with that ID in your organization. |

---

## Reservation resource availability

<a id="reservation-resource-availability"></a>

### Reservation resource availability overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability

Weekly recurring working hours of a [resource](#reservation-resources): one row per time block per weekday. A day can have several rows (for example 09:00–12:00 and 13:00–17:00). These rows define the [available slots](#reservation-available-slots) of every service the resource is linked to, and a reservation is only accepted on a resource inside one of its blocks.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-resource-availability` | [List availability](#reservation-resource-availability--list) |
| `GET` | `/reservation-resource-availability/:id` | [Get an availability block](#reservation-resource-availability--get) |
| `POST` | `/reservation-resource-availability` | [Create an availability block](#reservation-resource-availability--create) |
| `PATCH` | `/reservation-resource-availability/:id` | [Update an availability block](#reservation-resource-availability--update) |
| `DELETE` | `/reservation-resource-availability/:id` | [Delete an availability block](#reservation-resource-availability--delete) |

#### The availability object

```json
{
  "id": 91001,
  "organization_id": 456,
  "resource_id": 88,
  "day_of_week": 1,
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "breaks": [{ "start_time": "12:00", "end_time": "13:00" }],
  "valid_from": null,
  "valid_until": null,
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Owning organization. Required on create; must be the API key's organization. |
| `resource_id` | integer | [Resource](#reservation-resources) these hours belong to. Required on create. |
| `day_of_week` | integer | `0` = Sunday, `1` = Monday … `6` = Saturday. Required on create. |
| `start_time` | string | Block start, local time of the service, `HH:mm` or `HH:mm:ss` (returned as `HH:mm:ss`). Required on create. |
| `end_time` | string | Block end, same format. Required on create. A slot fits only if it ends by this time. |
| `breaks` | array | Items `{ "start_time", "end_time" }`. Default `[]`. Stored only: slot calculation and booking validation do not exclude breaks. To leave a gap, create two blocks instead. |
| `valid_from` | string (`YYYY-MM-DD`) \| null | Stored only: not applied by slot calculation or booking validation. |
| `valid_until` | string (`YYYY-MM-DD`) \| null | Stored only: not applied by slot calculation or booking validation. |
| `is_active` | boolean | Default `true`. Inactive blocks are ignored. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the block is deleted. |

#### Replacing a resource's schedule

The app replaces a schedule by listing the resource's rows, deleting each one and creating the new blocks. You can also [update](#reservation-resource-availability--update) a single block.

#### Related

- [Reservation resources](#reservation-resources)
- [Reservation resource exceptions](#reservation-resource-exceptions): date-specific closures and special hours
- [Reservation available slots](#reservation-available-slots)

<a id="reservation-resource-availability--list"></a>

### List reservation resource availability

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability/list

Returns a paginated list of weekly availability blocks. Filter by `resource_id` to get one resource's schedule.

#### Endpoint

`GET /reservation-resource-availability`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` | integer | No | Blocks of this resource. |
| `day_of_week` | integer | No | `0` (Sunday) to `6` (Saturday). |
| `is_active` | boolean | No | Only active or inactive blocks. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[day_of_week]=1`. |

Results are limited to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservation-resource-availability \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'resource_id=88' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[day_of_week]=1' \
  --data-urlencode '$sort[start_time]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 91001,
      "organization_id": 456,
      "resource_id": 88,
      "day_of_week": 1,
      "start_time": "09:00:00",
      "end_time": "17:00:00",
      "breaks": [],
      "valid_from": null,
      "valid_until": null,
      "is_active": true,
      "created_at": "2026-01-10T15:00:00.000Z",
      "updated_at": "2026-01-10T15:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="reservation-resource-availability--get"></a>

### Get a reservation resource availability block

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability/get

Returns one weekly availability block by ID.

#### Endpoint

`GET /reservation-resource-availability/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservation-resource-availability/91001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 91001,
  "organization_id": 456,
  "resource_id": 88,
  "day_of_week": 1,
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "breaks": [],
  "valid_from": null,
  "valid_until": null,
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No block with that ID in your organization, or it was deleted. |

<a id="reservation-resource-availability--create"></a>

### Create a reservation resource availability block

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability/create

Adds a weekly time block to a resource. Send one request per block (for example Monday 09:00–12:00 and Monday 13:00–17:00 are two blocks).

#### Endpoint

`POST /reservation-resource-availability`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `resource_id` | integer | Yes | [Resource](#reservation-resources) ID. |
| `day_of_week` | integer | Yes | `0` (Sunday) to `6` (Saturday). |
| `start_time` | string | Yes | `HH:mm` or `HH:mm:ss`. |
| `end_time` | string | Yes | `HH:mm` or `HH:mm:ss`. |
| `is_active` | boolean | No | Default `true`. |
| `breaks` | array | No | `{ "start_time", "end_time" }` items. Stored only. |
| `valid_from`, `valid_until` | string (`YYYY-MM-DD`) | No | Stored only. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/reservation-resource-availability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "resource_id": 88,
    "day_of_week": 1,
    "start_time": "09:00",
    "end_time": "12:00"
  }'
```

#### Response

Returns the created [availability object](#reservation-resource-availability).

```json
{
  "id": 91002,
  "organization_id": 456,
  "resource_id": 88,
  "day_of_week": 1,
  "start_time": "09:00:00",
  "end_time": "12:00:00",
  "breaks": [],
  "valid_from": null,
  "valid_until": null,
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field, `day_of_week` outside 0–6, or a time not in `HH:mm[:ss]` format. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservation-resource-availability--update"></a>

### Update a reservation resource availability block

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability/update

Partially updates one weekly availability block. Only the fields you send change.

#### Endpoint

`PATCH /reservation-resource-availability/:id`

#### Body

Any field of the [availability object](#reservation-resource-availability) except `id`. Unknown fields return `400`. `breaks` is replaced as a whole.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-resource-availability/91001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "08:30",
    "end_time": "16:30"
  }'
```

#### Response

Returns the updated [availability object](#reservation-resource-availability).

```json
{
  "id": 91001,
  "organization_id": 456,
  "resource_id": 88,
  "day_of_week": 1,
  "start_time": "08:30:00",
  "end_time": "16:30:00",
  "breaks": [],
  "valid_from": null,
  "valid_until": null,
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-03-02T11:20:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid or unknown field, or a time not in `HH:mm[:ss]` format. |
| `404 Not Found` | No block with that ID in your organization. |

<a id="reservation-resource-availability--delete"></a>

### Delete a reservation resource availability block

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability/delete

Removes a weekly availability block. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get, and its hours stop producing slots.

#### Endpoint

`DELETE /reservation-resource-availability/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservation-resource-availability/91001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [availability object](#reservation-resource-availability) with `deleted_at` set.

```json
{
  "id": 91001,
  "organization_id": 456,
  "resource_id": 88,
  "day_of_week": 1,
  "start_time": "09:00:00",
  "end_time": "17:00:00",
  "is_active": true,
  "deleted_at": "2026-04-22T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No block with that ID in your organization. |

---

## Reservation resource exceptions

<a id="reservation-resource-exceptions"></a>

### Reservation resource exceptions overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions

Date-specific overrides of the weekly [availability](#reservation-resource-availability): close a resource (or the whole organization) on a date, or give a resource different hours that day.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-resource-exceptions` | [List exceptions](#reservation-resource-exceptions--list) |
| `GET` | `/reservation-resource-exceptions/:id` | [Get an exception](#reservation-resource-exceptions--get) |
| `POST` | `/reservation-resource-exceptions` | [Create an exception](#reservation-resource-exceptions--create) |
| `PATCH` | `/reservation-resource-exceptions/:id` | [Update an exception](#reservation-resource-exceptions--update) |
| `DELETE` | `/reservation-resource-exceptions/:id` | [Delete an exception](#reservation-resource-exceptions--delete) |

#### The exception object

```json
{
  "id": 92001,
  "organization_id": 456,
  "resource_id": 88,
  "exception_type": "special_hours",
  "date": "2026-12-24T00:00:00.000Z",
  "start_time": "10:00:00",
  "end_time": "14:00:00",
  "reason": "Short day",
  "is_recurring_yearly": false,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-01T15:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Owning organization. Required on create; must be the API key's organization. |
| `resource_id` | integer \| null | [Resource](#reservation-resources) affected. `null` = organization-wide (applies to every resource). |
| `exception_type` | string | One of `blocked`, `special_hours`, `holiday`. Required on create. See below. |
| `date` | string (`YYYY-MM-DD`) | Date affected. Required on create. Send `YYYY-MM-DD`; it is returned as a midnight timestamp (`2026-12-24T00:00:00.000Z`), so use the date part. |
| `start_time` | string \| null | For `special_hours`: opening time that day, `HH:mm`. |
| `end_time` | string \| null | For `special_hours`: closing time that day, `HH:mm`. |
| `reason` | string \| null | Free-text reason, max 255 characters. |
| `is_recurring_yearly` | boolean | Default `false`. Stored only: exceptions apply only to their exact `date`; create one per year if needed. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the exception is deleted. |

##### `exception_type`

| Value | Effect |
|---|---|
| `blocked` | With a `resource_id`: the resource is unavailable all day (no slots from it, and reservations needing it are rejected). With `resource_id: null`: the whole date is closed, [available slots](#reservation-available-slots) returns `"This date is blocked"` for every service, and reservations on services with linked resources are rejected. |
| `special_hours` | Replaces the resource's weekly hours with `start_time`–`end_time` on that date when computing available slots. Requires a `resource_id`; organization-wide `special_hours` are ignored. Reservation creation still validates against the weekly hours. |
| `holiday` | Stored only; has no effect on slots or bookings. Use `blocked` to close a date. |

#### Related

- [Reservation resource availability](#reservation-resource-availability)
- [Reservation resources](#reservation-resources)
- [Reservation available slots](#reservation-available-slots)

<a id="reservation-resource-exceptions--list"></a>

### List reservation resource exceptions

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions/list

Returns a paginated list of date exceptions.

#### Endpoint

`GET /reservation-resource-exceptions`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_id` | integer | No | Exceptions of this resource only. Organization-wide exceptions have `resource_id: null`; omit this filter to get them together with every resource's exceptions. |
| `exception_type` | string | No | `blocked`, `special_hours` or `holiday`. |
| `date` | string (`YYYY-MM-DD`) | No | Exceptions on this date. Ranges: `date[$gte]=2026-12-01&date[$lte]=2026-12-31`. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[date]=-1`. |

Results are limited to the API key's organization automatically.

#### Request

All exceptions in December 2026:

```bash
curl -G https://integrations.achieveapex.com/reservation-resource-exceptions \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'date[$gte]=2026-12-01' \
  --data-urlencode 'date[$lte]=2026-12-31' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[date]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 92002,
      "organization_id": 456,
      "resource_id": null,
      "exception_type": "blocked",
      "date": "2026-12-25T00:00:00.000Z",
      "start_time": null,
      "end_time": null,
      "reason": "Christmas",
      "is_recurring_yearly": false,
      "created_at": "2026-11-01T15:00:00.000Z",
      "updated_at": "2026-11-01T15:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="reservation-resource-exceptions--get"></a>

### Get a reservation resource exception

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions/get

Returns one date exception by ID.

#### Endpoint

`GET /reservation-resource-exceptions/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservation-resource-exceptions/92001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 92001,
  "organization_id": 456,
  "resource_id": 88,
  "exception_type": "special_hours",
  "date": "2026-12-24T00:00:00.000Z",
  "start_time": "10:00:00",
  "end_time": "14:00:00",
  "reason": "Short day",
  "is_recurring_yearly": false,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-01T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No exception with that ID in your organization, or it was deleted. |

<a id="reservation-resource-exceptions--create"></a>

### Create a reservation resource exception

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions/create

Adds a date exception for a resource or for the whole organization.

#### Endpoint

`POST /reservation-resource-exceptions`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `exception_type` | string | Yes | `blocked`, `special_hours` or `holiday`. |
| `date` | string (`YYYY-MM-DD`) | Yes | Date affected. |
| `resource_id` | integer \| null | No | Resource affected; omit or `null` for organization-wide. |
| `start_time`, `end_time` | string | For `special_hours` | Hours that day, `HH:mm`. |
| `reason` | string | No | Max 255 characters. |
| `is_recurring_yearly` | boolean | No | Default `false`. Stored only. |

#### Request

Close the whole organization on a date:

```bash
curl -X POST https://integrations.achieveapex.com/reservation-resource-exceptions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "resource_id": null,
    "exception_type": "blocked",
    "date": "2026-12-25",
    "reason": "Christmas"
  }'
```

Shorter hours for one resource:

```bash
curl -X POST https://integrations.achieveapex.com/reservation-resource-exceptions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "resource_id": 88,
    "exception_type": "special_hours",
    "date": "2026-12-24",
    "start_time": "10:00",
    "end_time": "14:00",
    "reason": "Short day"
  }'
```

#### Response

Returns the created [exception object](#reservation-resource-exceptions).

```json
{
  "id": 92001,
  "organization_id": 456,
  "resource_id": 88,
  "exception_type": "special_hours",
  "date": "2026-12-24T00:00:00.000Z",
  "start_time": "10:00:00",
  "end_time": "14:00:00",
  "reason": "Short day",
  "is_recurring_yearly": false,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-01T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field, invalid `exception_type`, or `date` not in `YYYY-MM-DD` format. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservation-resource-exceptions--update"></a>

### Update a reservation resource exception

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions/update

Partially updates a date exception. Only the fields you send change.

#### Endpoint

`PATCH /reservation-resource-exceptions/:id`

#### Body

Any field of the [exception object](#reservation-resource-exceptions) except `id`. Unknown fields return `400`.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-resource-exceptions/92001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "09:00",
    "end_time": "13:00"
  }'
```

#### Response

Returns the updated [exception object](#reservation-resource-exceptions).

```json
{
  "id": 92001,
  "organization_id": 456,
  "resource_id": 88,
  "exception_type": "special_hours",
  "date": "2026-12-24T00:00:00.000Z",
  "start_time": "09:00:00",
  "end_time": "13:00:00",
  "reason": "Short day",
  "is_recurring_yearly": false,
  "created_at": "2026-11-01T15:00:00.000Z",
  "updated_at": "2026-11-02T09:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid or unknown field. |
| `404 Not Found` | No exception with that ID in your organization. |

<a id="reservation-resource-exceptions--delete"></a>

### Delete a reservation resource exception

Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions/delete

Removes a date exception, restoring the weekly hours on that date. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get.

#### Endpoint

`DELETE /reservation-resource-exceptions/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservation-resource-exceptions/92001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [exception object](#reservation-resource-exceptions) with `deleted_at` set.

```json
{
  "id": 92001,
  "organization_id": 456,
  "resource_id": 88,
  "exception_type": "special_hours",
  "date": "2026-12-24T00:00:00.000Z",
  "deleted_at": "2026-12-01T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No exception with that ID in your organization. |

---

## Reservation resources

<a id="reservation-resources"></a>

### Reservation resources overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-resources

A resource is something a reservation occupies: a person (staff member), a room, a table, a piece of equipment or a vehicle. Resources have a capacity, a weekly [availability](#reservation-resource-availability), date [exceptions](#reservation-resource-exceptions), and are attached to services through [service resources](#reservation-service-resources).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-resources` | [List resources](#reservation-resources--list) |
| `GET` | `/reservation-resources/:id` | [Get a resource](#reservation-resources--get) |
| `POST` | `/reservation-resources` | [Create a resource](#reservation-resources--create) |
| `PATCH` | `/reservation-resources/:id` | [Update a resource](#reservation-resources--update) |
| `DELETE` | `/reservation-resources/:id` | [Delete a resource](#reservation-resources--delete) |

#### The resource object

```json
{
  "id": 88,
  "organization_id": 456,
  "resource_type": "person",
  "name": "Dr. Smith",
  "description": "General practitioner",
  "user_id": 789,
  "capacity": 1,
  "metadata": { "floor": 2 },
  "color": "#3B82F6",
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Owning organization. Required on create; must be the API key's organization. |
| `resource_type` | string | One of `person`, `room`, `equipment`, `vehicle`, `other`. Required on create. With `any_available` [service resources](#reservation-service-resources), any active resource of the same type can be assigned. |
| `name` | string | Display name, max 255 characters. Required on create. |
| `description` | string \| null | Description. |
| `user_id` | integer \| null | For `person` resources, the organization user this resource represents. That user receives the staff notification email when a reservation is assigned to the resource. |
| `capacity` | integer | How many reservation units the resource can hold at the same time (each assignment uses the link's `quantity_required`). Default `1`. |
| `metadata` | object \| null | Free-form attributes for your own use. |
| `color` | string \| null | Calendar color (hex), max 50 characters. |
| `is_active` | boolean | Default `true`. Inactive resources are not picked by `any_available` assignment. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the resource is deleted. |

#### Related

- [Reservation resource availability](#reservation-resource-availability): weekly hours
- [Reservation resource exceptions](#reservation-resource-exceptions): blocked dates and special hours
- [Reservation service resources](#reservation-service-resources): attach resources to services
- [Reservations](#reservations)

<a id="reservation-resources--list"></a>

### List reservation resources

Source: https://www.achieveapex.com/docs/api-reference/reservation-resources/list

Returns a paginated list of the organization's reservation resources.

#### Endpoint

`GET /reservation-resources`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `resource_type` | string | No | `person`, `room`, `equipment`, `vehicle` or `other`. |
| `is_active` | boolean | No | Only active (`true`) or inactive (`false`) resources. |
| `user_id` | integer | No | The resource linked to this user. |
| `id[$in][]` | integer | No | Only these IDs. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. |
| `$select[]` | string | No | Return only these fields. |

Any field of the [resource object](#reservation-resources) can be used as a filter. Results are limited to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservation-resources \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'is_active=true' \
  --data-urlencode 'resource_type=room' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[name]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 90,
      "organization_id": 456,
      "resource_type": "room",
      "name": "Room A",
      "description": null,
      "user_id": null,
      "capacity": 4,
      "metadata": null,
      "color": "#10B981",
      "is_active": true,
      "created_at": "2026-01-10T15:00:00.000Z",
      "updated_at": "2026-01-10T15:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="reservation-resources--get"></a>

### Get a reservation resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-resources/get

Returns one reservation resource by ID.

#### Endpoint

`GET /reservation-resources/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservation-resources/88 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 88,
  "organization_id": 456,
  "resource_type": "person",
  "name": "Dr. Smith",
  "description": "General practitioner",
  "user_id": 789,
  "capacity": 1,
  "metadata": null,
  "color": "#3B82F6",
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No resource with that ID in your organization, or it was deleted. |

<a id="reservation-resources--create"></a>

### Create a reservation resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-resources/create

Creates a bookable resource. Give it weekly hours with [resource availability](#reservation-resource-availability--create) and attach it to services with [service resources](#reservation-service-resources--create); a resource without availability is never free.

#### Endpoint

`POST /reservation-resources`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `resource_type` | string | Yes | `person`, `room`, `equipment`, `vehicle` or `other`. |
| `name` | string | Yes | Display name, max 255 characters. |
| `description` | string | No | Description. |
| `user_id` | integer | No | Organization user, for `person` resources. |
| `capacity` | integer | No | Simultaneous capacity. Default `1`. |
| `metadata` | object | No | Free-form attributes. |
| `color` | string | No | Hex color. |
| `is_active` | boolean | No | Default `true`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/reservation-resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "resource_type": "person",
    "name": "Dr. Smith",
    "user_id": 789,
    "capacity": 1,
    "color": "#3B82F6"
  }'
```

#### Response

Returns the created [resource object](#reservation-resources).

```json
{
  "id": 88,
  "organization_id": 456,
  "resource_type": "person",
  "name": "Dr. Smith",
  "description": null,
  "user_id": 789,
  "capacity": 1,
  "metadata": null,
  "color": "#3B82F6",
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field or invalid `resource_type`. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservation-resources--update"></a>

### Update a reservation resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-resources/update

Partially updates a reservation resource. Only the fields you send change.

#### Endpoint

`PATCH /reservation-resources/:id`

#### Body

Any field of the [resource object](#reservation-resources) except `id`. Unknown fields return `400`. `metadata` is replaced as a whole.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-resources/90 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Room A (large)",
    "capacity": 6
  }'
```

#### Response

Returns the updated [resource object](#reservation-resources).

```json
{
  "id": 90,
  "organization_id": 456,
  "resource_type": "room",
  "name": "Room A (large)",
  "capacity": 6,
  "is_active": true,
  "updated_at": "2026-03-02T11:20:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid or unknown field. |
| `404 Not Found` | No resource with that ID in your organization. |

<a id="reservation-resources--delete"></a>

### Delete a reservation resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-resources/delete

Deletes a reservation resource. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get. Its availability rows, exceptions and service links are not deleted automatically; delete them with their own endpoints, or set `is_active: false` on the resource instead.

#### Endpoint

`DELETE /reservation-resources/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservation-resources/90 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [resource object](#reservation-resources) with `deleted_at` set.

```json
{
  "id": 90,
  "organization_id": 456,
  "resource_type": "room",
  "name": "Room A",
  "deleted_at": "2026-04-22T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No resource with that ID in your organization. |

---

## Reservation service resources

<a id="reservation-service-resources"></a>

### Reservation service resources overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources

A service resource links a [resource](#reservation-resources) to a [service](#reservation-services) and says how it is used when someone books that service: whether it is required, optional or any resource of the same type, and how much of its capacity one booking takes. Services without links are bookable 08:00–18:00 without resource checks.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-service-resources` | [List service resources](#reservation-service-resources--list) |
| `GET` | `/reservation-service-resources/:id` | [Get a service resource](#reservation-service-resources--get) |
| `POST` | `/reservation-service-resources` | [Create a service resource](#reservation-service-resources--create) |
| `PATCH` | `/reservation-service-resources/:id` | [Update a service resource](#reservation-service-resources--update) |
| `DELETE` | `/reservation-service-resources/:id` | [Delete a service resource](#reservation-service-resources--delete) |

#### The service resource object

```json
{
  "id": 7001,
  "organization_id": 456,
  "service_id": 12,
  "resource_id": 88,
  "assignment_mode": "required",
  "quantity_required": 1,
  "priority": 0,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Owning organization. Required on create; must be the API key's organization. |
| `service_id` | integer | [Service](#reservation-services). Required on create. |
| `resource_id` | integer | [Resource](#reservation-resources). Required on create. |
| `assignment_mode` | string | How the resource is used on booking. Default `required`. See below. |
| `quantity_required` | integer | Capacity units of the resource one reservation uses. Default `1`, minimum `1`. |
| `priority` | integer | Default `0`. Stored ordering value; not used by automatic assignment. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the link is deleted. |

##### `assignment_mode`

| Value | Behavior when a reservation is created |
|---|---|
| `required` | The resource must be within its weekly hours, not blocked that day, and have `quantity_required` free capacity, or the reservation is rejected. |
| `optional` | Assigned when free; skipped otherwise. |
| `any_available` | Any active resource with the same `resource_type` that is free is assigned; the reservation is rejected when none is. |

The weekly hours of every linked resource also define which [slots](#reservation-available-slots) the service offers.

#### Related

- [Reservation services](#reservation-services)
- [Reservation resources](#reservation-resources)
- [Reservation resource availability](#reservation-resource-availability)

<a id="reservation-service-resources--list"></a>

### List reservation service resources

Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources/list

Returns a paginated list of service-resource links. Filter by `service_id` to see the resources of one service, or by `resource_id` to see the services a resource serves.

#### Endpoint

`GET /reservation-service-resources`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `service_id` | integer | No | Links of this service. |
| `resource_id` | integer | No | Links of this resource. |
| `assignment_mode` | string | No | `required`, `optional` or `any_available`. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[priority]=1`. |

Results are limited to the API key's organization automatically. The resource itself is not embedded; fetch it with [Get a resource](#reservation-resources--get) or `GET /reservation-resources?id[$in][]=...`.

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservation-service-resources \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'service_id=12' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 7001,
      "organization_id": 456,
      "service_id": 12,
      "resource_id": 88,
      "assignment_mode": "required",
      "quantity_required": 1,
      "priority": 0,
      "created_at": "2026-01-10T15:00:00.000Z",
      "updated_at": "2026-01-10T15:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

<a id="reservation-service-resources--get"></a>

### Get a reservation service resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources/get

Returns one service-resource link by ID.

#### Endpoint

`GET /reservation-service-resources/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservation-service-resources/7001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 7001,
  "organization_id": 456,
  "service_id": 12,
  "resource_id": 88,
  "assignment_mode": "required",
  "quantity_required": 1,
  "priority": 0,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No link with that ID in your organization, or it was deleted. |

<a id="reservation-service-resources--create"></a>

### Create a reservation service resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources/create

Links a resource to a service.

#### Endpoint

`POST /reservation-service-resources`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `service_id` | integer | Yes | [Service](#reservation-services) ID. |
| `resource_id` | integer | Yes | [Resource](#reservation-resources) ID. |
| `assignment_mode` | string | No | `required` (default), `optional` or `any_available`. |
| `quantity_required` | integer | No | Capacity used per reservation. Default `1`. |
| `priority` | integer | No | Default `0`. |

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/reservation-service-resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "service_id": 12,
    "resource_id": 88,
    "assignment_mode": "required",
    "quantity_required": 1
  }'
```

#### Response

Returns the created [service resource object](#reservation-service-resources).

```json
{
  "id": 7001,
  "organization_id": 456,
  "service_id": 12,
  "resource_id": 88,
  "assignment_mode": "required",
  "quantity_required": 1,
  "priority": 0,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field or invalid `assignment_mode`. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservation-service-resources--update"></a>

### Update a reservation service resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources/update

Partially updates a service-resource link. Only the fields you send change.

#### Endpoint

`PATCH /reservation-service-resources/:id`

#### Body

Any field of the [service resource object](#reservation-service-resources) except `id`. Unknown fields return `400`.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-service-resources/7001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment_mode": "optional",
    "quantity_required": 2
  }'
```

#### Response

Returns the updated [service resource object](#reservation-service-resources).

```json
{
  "id": 7001,
  "organization_id": 456,
  "service_id": 12,
  "resource_id": 88,
  "assignment_mode": "optional",
  "quantity_required": 2,
  "priority": 0,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-03-02T11:20:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid or unknown field. |
| `404 Not Found` | No link with that ID in your organization. |

<a id="reservation-service-resources--delete"></a>

### Delete a reservation service resource

Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources/delete

Unlinks a resource from a service. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get. Existing reservations keep their assigned resources.

#### Endpoint

`DELETE /reservation-service-resources/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservation-service-resources/7001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [service resource object](#reservation-service-resources) with `deleted_at` set.

```json
{
  "id": 7001,
  "organization_id": 456,
  "service_id": 12,
  "resource_id": 88,
  "assignment_mode": "required",
  "quantity_required": 1,
  "priority": 0,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-04-22T10:00:00.000Z",
  "deleted_at": "2026-04-22T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No link with that ID in your organization. |

---

## Reservation services

<a id="reservation-services"></a>

### Reservation services overview

Source: https://www.achieveapex.com/docs/api-reference/reservation-services

A reservation service is something customers can book (a consultation, a table, a class): its duration, how many bookings fit in one slot, booking-window rules, price and whether it shows on public booking pages. Every [reservation](#reservations) belongs to one service.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservation-services` | [List services](#reservation-services--list) |
| `GET` | `/reservation-services/:id` | [Get a service](#reservation-services--get) |
| `POST` | `/reservation-services` | [Create a service](#reservation-services--create) |
| `PATCH` | `/reservation-services/:id` | [Update a service](#reservation-services--update) |
| `DELETE` | `/reservation-services/:id` | [Delete a service](#reservation-services--delete) |

#### The service object

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Consultation",
  "description": "60-minute strategy call",
  "duration_minutes": 60,
  "buffer_before_minutes": 0,
  "buffer_after_minutes": 0,
  "slot_capacity": 4,
  "max_party_size": 8,
  "capacity_mode": "per_slot",
  "price": "150.00",
  "currency_id": 3,
  "exchange_rate": "1.000000",
  "currency_symbol": "$",
  "currency_format": "{symbol}{amount}",
  "decimal_places": 2,
  "thousand_separator": ",",
  "decimal_separator": ".",
  "max_daily_bookings": null,
  "max_advance_days": 90,
  "min_advance_hours": 2,
  "requires_confirmation": false,
  "auto_confirm": true,
  "allow_cancellation": true,
  "cancellation_deadline_hours": 24,
  "is_public": true,
  "booking_instructions": "Please arrive 10 minutes early.",
  "color": "#2563EB",
  "image_url": "https://files.example.com/consultation.jpg",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "is_active": true,
  "product_id": null,
  "timezone": "America/New_York",
  "slot_interval": 30,
  "duration_mode": "fixed",
  "duration_options": [],
  "capacity_unit": "bookings",
  "min_party_size": 1,
  "pricing_unit": "per_booking",
  "payment_mode": "deposit",
  "deposit_type": "percent",
  "deposit_value": 30,
  "payment_hold_minutes": 30,
  "payment_gateway_id": null,
  "allow_customer_reschedule": true,
  "reschedule_deadline_hours": 24,
  "cancellation_policy_text": "Free cancellation up to 24 hours before. The deposit is not refundable after that.",
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-03-02T11:20:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Owning organization. Required on create; must be the API key's organization. |
| `name` | string | Service name, max 255 characters. Required on create. |
| `description` | string \| null | Description shown on booking pages. |
| `duration_minutes` | integer | Length of one booking, minimum `1`. Required on create. Used to compute the reservation `end_datetime` and the slots. With `duration_mode: "flexible"` it is the default length when the reservation does not send `duration_minutes`. |
| `buffer_before_minutes` | integer | Default `0`. Free minutes kept before each booking: a slot is not offered when this gap overlaps another booking of the same resources or service. |
| `buffer_after_minutes` | integer | Default `0`. Free minutes kept after each booking, same rule as `buffer_before_minutes`. |
| `slot_capacity` | integer | How much fits in the same time slot. Default `1`, minimum `1`. Counted in reservations when `capacity_unit` is `bookings`, in people (sum of `party_size`) when it is `people`. |
| `max_party_size` | integer | Maximum `party_size` per reservation. Default `1`, minimum `1`. |
| `capacity_mode` | string | `per_slot` (default) or `per_resource`. With `per_slot`, creating a reservation fails when `slot_capacity` overlapping reservations already exist; with `per_resource` that check is skipped and only the linked resources' capacity applies. [Available slots](#reservation-available-slots) always count against `slot_capacity`. |
| `price` | string (decimal) \| null | Price, minimum `0`. Returned as a decimal string. Send a number. |
| `currency_id` | integer \| null | Organization currency (`organization_currencies` ID) of `price`. When set and `exchange_rate` is not sent, the server fills `exchange_rate` and the formatting fields below. |
| `exchange_rate` | string (decimal) \| null | Rate from this currency to the organization's base currency. Filled automatically from `currency_id` unless you send it. |
| `currency_symbol` | string \| null | Currency symbol, e.g. `$`. Filled from `currency_id` when empty. |
| `currency_format` | string \| null | Display pattern, e.g. `{symbol}{amount}`. Filled from `currency_id` when empty. |
| `decimal_places` | integer \| null | Decimals to display. Default `2`. |
| `thousand_separator` | string \| null | Default `,`. |
| `decimal_separator` | string \| null | Default `.`. |
| `max_daily_bookings` | integer \| null | Maximum `pending`/`confirmed` reservations per day for this service, minimum `1`. `null` = no limit. Enforced on create. |
| `max_advance_days` | integer | How many days ahead customers can book. Default `30`, minimum `1`. |
| `min_advance_hours` | integer | Minimum notice in hours before a booking starts. Default `1`, minimum `0`. Applies to customer and AI bookings; staff bookings (`source: "manual"`) skip it. |
| `requires_confirmation` | boolean | Default `false`. Stored setting; the initial status is controlled by `auto_confirm`. |
| `auto_confirm` | boolean | Default `true`. When `true`, new reservations are created as `confirmed`; otherwise the `status` sent on create is kept (default `pending`). |
| `allow_cancellation` | boolean | Default `true`. Whether the customer can cancel from the booking's manage link. Staff and the API can always cancel. |
| `cancellation_deadline_hours` | integer | Default `24`, minimum `0`. The customer can cancel from the manage link until this many hours before the start. Not enforced for staff or the API. |
| `is_public` | boolean | Default `true`. Only services with `is_public: true` and `is_active: true` appear on [booking links](#reservation-booking-links). |
| `booking_instructions` | string \| null | Instructions shown on the public booking page. |
| `color` | string \| null | Calendar color (hex), max 50 characters. |
| `image_url` | string \| null | Image URL shown on booking pages. |
| `video_url` | string \| null | Video shown on the public booking page, max 2000 characters. Accepts YouTube, Vimeo, Loom, Wistia, Google Drive, Dropbox and other embeddable links, an `<iframe>` embed code, or a direct video file URL; unsupported links return `400`. |
| `is_active` | boolean | Default `true`. Inactive services cannot be booked and return no slots. |
| `product_id` | integer \| null | Optional link to a [product](#products). |
| `timezone` | string \| null | IANA timezone of the service, e.g. `America/New_York`. Default `UTC`; while it is `UTC` the organization timezone is used when the organization has one. Reservation times are wall-clock times in this zone. |
| `slot_interval` | integer | Minutes between consecutive slot start times. Default `30`, minimum `5`. |
| `duration_mode` | string | `fixed` (default: every booking lasts `duration_minutes`) or `flexible` (the customer picks one of `duration_options`). |
| `duration_options` | array of integers | Lengths in minutes the customer can choose when `duration_mode` is `flexible`, e.g. `[120, 240, 480]`. Each between `5` and `10080`, up to 24 items. When empty on a flexible service, `[duration_minutes]` is stored. |
| `capacity_unit` | string | `bookings` (default: each reservation uses 1 of `slot_capacity`) or `people` (each reservation uses its `party_size`, e.g. a restaurant with 20 seats). |
| `min_party_size` | integer | Minimum `party_size` per reservation. Default `1`. Cannot be greater than `max_party_size` (`400` otherwise). |
| `pricing_unit` | string | How `price` is applied: `per_booking` (default), `per_person` (× `party_size`) or `per_hour` (× booked minutes / 60). |
| `payment_mode` | string | `none` (default: no online payment), `optional` (the customer chooses pay now or pay at the venue), `deposit` (part of the total is paid online to confirm) or `full` (the whole total is paid online to confirm). |
| `deposit_type` | string | `percent` (default) or `fixed`. Used when `payment_mode` is `deposit`. |
| `deposit_value` | number \| null | Deposit as a percent of the total (`0`–`100`) or a fixed amount in the service currency. Required and greater than `0` when `payment_mode` is `deposit`. |
| `payment_hold_minutes` | integer | Default `30` (`5`–`10080`). How long an unpaid online booking (`status: "awaiting_payment"`) keeps its slot before it is cancelled with `cancellation_reason: "payment_expired"`. |
| `payment_gateway_id` | integer \| null | Organization payment gateway used for payment links. `null` = the organization default gateway. Must belong to the same organization. |
| `allow_customer_reschedule` | boolean | Default `false`. Whether the customer can move the booking from its manage link. |
| `reschedule_deadline_hours` | integer \| null | The customer can reschedule until this many hours before the start. `null` = until it starts. |
| `cancellation_policy_text` | string \| null | Policy shown to the customer before booking and paying, max 5000 characters. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the service is deleted. |

#### Related

- [Reservations](#reservations)
- [Reservation service resources](#reservation-service-resources): which resources a service needs
- [Reservation available slots](#reservation-available-slots)
- [Reservation booking links](#reservation-booking-links)

<a id="reservation-services--list"></a>

### List reservation services

Source: https://www.achieveapex.com/docs/api-reference/reservation-services/list

Returns a paginated list of the organization's reservation services.

#### Endpoint

`GET /reservation-services`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `is_active` | boolean | No | Only active (`true`) or inactive (`false`) services. |
| `is_public` | boolean | No | Only services shown (or not) on booking links. |
| `name` | string | No | Exact name. |
| `id[$in][]` | integer | No | Only these IDs. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[name]=1`. |
| `$select[]` | string | No | Return only these fields. |

Any field of the [service object](#reservation-services) can be used as a filter. Results are limited to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservation-services \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'is_active=true' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[name]=1'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 12,
      "organization_id": 456,
      "name": "Consultation",
      "description": "60-minute strategy call",
      "duration_minutes": 60,
      "slot_capacity": 4,
      "max_party_size": 8,
      "capacity_mode": "per_slot",
      "price": "150.00",
      "currency_id": 3,
      "max_advance_days": 90,
      "min_advance_hours": 2,
      "auto_confirm": true,
      "is_public": true,
      "is_active": true,
      "timezone": "America/New_York",
      "slot_interval": 30,
      "created_at": "2026-01-10T15:00:00.000Z",
      "updated_at": "2026-03-02T11:20:00.000Z",
      "deleted_at": null
    }
  ]
}
```

Each item contains every field of the [service object](#reservation-services) (shortened above).

<a id="reservation-services--get"></a>

### Get a reservation service

Source: https://www.achieveapex.com/docs/api-reference/reservation-services/get

Returns one reservation service by ID.

#### Endpoint

`GET /reservation-services/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservation-services/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the full [service object](#reservation-services).

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Consultation",
  "duration_minutes": 60,
  "slot_capacity": 4,
  "max_party_size": 8,
  "capacity_mode": "per_slot",
  "price": "150.00",
  "currency_id": 3,
  "is_public": true,
  "is_active": true,
  "timezone": "America/New_York",
  "slot_interval": 30,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-03-02T11:20:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No service with that ID in your organization, or it was deleted. |

<a id="reservation-services--create"></a>

### Create a reservation service

Source: https://www.achieveapex.com/docs/api-reference/reservation-services/create

Creates a bookable service.

#### Endpoint

`POST /reservation-services`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `name` | string | Yes | Service name, max 255 characters. |
| `duration_minutes` | integer | Yes | Length of one booking, minimum `1`. |
| `slot_capacity` | integer | No | Reservations per slot. Default `1`. |
| `max_party_size` | integer | No | Maximum people per reservation. Default `1`. |
| `capacity_mode` | string | No | `per_slot` (default) or `per_resource`. |
| `slot_interval` | integer | No | Minutes between slot starts. Default `30`, minimum `5`. |
| `timezone` | string | No | IANA timezone. Default `UTC`. |
| `max_advance_days` | integer | No | Default `30`. |
| `min_advance_hours` | integer | No | Default `1`. |
| `max_daily_bookings` | integer | No | Daily limit, `null` for none. |
| `auto_confirm` | boolean | No | Default `true`. |
| `is_public` | boolean | No | Default `true`. |
| `is_active` | boolean | No | Default `true`. |
| `price` | number | No | Price, minimum `0`. |
| `currency_id` | integer | No | Currency of the price; fills the currency formatting fields. |

Every other field of the [service object](#reservation-services) except `id`, `created_at`, `updated_at` and `deleted_at` can also be sent.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/reservation-services \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "Consultation",
    "description": "60-minute strategy call",
    "duration_minutes": 60,
    "slot_capacity": 4,
    "max_party_size": 8,
    "slot_interval": 30,
    "price": 150,
    "currency_id": 3,
    "max_advance_days": 90,
    "min_advance_hours": 2,
    "auto_confirm": true,
    "is_public": true,
    "color": "#2563EB",
    "timezone": "America/New_York"
  }'
```

#### Response

Returns the created [service object](#reservation-services).

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Consultation",
  "description": "60-minute strategy call",
  "duration_minutes": 60,
  "slot_capacity": 4,
  "max_party_size": 8,
  "price": "150.00",
  "currency_id": 3,
  "exchange_rate": "1.000000",
  "currency_symbol": "$",
  "timezone": "America/New_York",
  "slot_interval": 30,
  "is_active": true,
  "created_at": "2026-01-10T15:00:00.000Z",
  "updated_at": "2026-01-10T15:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field, value below its minimum, invalid `capacity_mode`, or a `video_url` that cannot be embedded. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservation-services--update"></a>

### Update a reservation service

Source: https://www.achieveapex.com/docs/api-reference/reservation-services/update

Partially updates a reservation service. Only the fields you send change. Existing reservations keep their stored `end_datetime` when `duration_minutes` changes.

#### Endpoint

`PATCH /reservation-services/:id`

#### Body

Any field of the [service object](#reservation-services) except `id`. Unknown fields return `400`. When `currency_id` changes and `exchange_rate` is not sent, the exchange rate and currency formatting fields are filled again.

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/reservation-services/12 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Strategy consultation",
    "duration_minutes": 90,
    "slot_interval": 15
  }'
```

#### Response

Returns the updated [service object](#reservation-services).

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Strategy consultation",
  "duration_minutes": 90,
  "slot_interval": 15,
  "is_active": true,
  "updated_at": "2026-03-02T11:20:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid or unknown field, or a `video_url` that cannot be embedded. |
| `404 Not Found` | No service with that ID in your organization. |

<a id="reservation-services--delete"></a>

### Delete a reservation service

Source: https://www.achieveapex.com/docs/api-reference/reservation-services/delete

Deletes a reservation service. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get. Existing reservations of the service are not changed. To stop new bookings but keep the service visible to your team, [update](#reservation-services--update) it with `is_active: false` instead.

#### Endpoint

`DELETE /reservation-services/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservation-services/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [service object](#reservation-services) with `deleted_at` set.

```json
{
  "id": 12,
  "organization_id": 456,
  "name": "Consultation",
  "is_active": true,
  "deleted_at": "2026-04-22T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No service with that ID in your organization. |

---

## Reservations

<a id="reservations"></a>

### Reservations overview

Source: https://www.achieveapex.com/docs/api-reference/reservations

A reservation books a contact into a [reservation service](#reservation-services) at a given start time. Use it to list the calendar, book appointments from your own systems, and move bookings through `pending` → `confirmed` → `completed` (or `cancelled` / `no_show`).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/reservations` | [List reservations](#reservations--list) |
| `GET` | `/reservations/:id` | [Get a reservation](#reservations--get) |
| `POST` | `/reservations` | [Create a reservation](#reservations--create) |
| `PATCH` | `/reservations/:id` | [Update a reservation](#reservations--update) |
| `DELETE` | `/reservations/:id` | [Delete a reservation](#reservations--delete) |

#### Typical flow

1. [List services](#reservation-services--list) (`is_active=true`).
2. [Get available slots](#reservation-available-slots--list) for a service and date.
3. [Create the reservation](#reservations--create) with the slot `start_datetime`.
4. [Update it](#reservations--update) to confirm, reschedule, complete or cancel.

#### Date and time format

`start_datetime` and `end_datetime` are **wall-clock times** in the service's `timezone`, stored with a `Z` suffix. `2026-04-25T15:00:00.000Z` means 15:00 local time of the service, not 15:00 UTC. Any offset you send is stripped and the clock time is kept (`2026-04-25T15:00:00-05:00` is stored as `2026-04-25T15:00:00.000Z`). The slots returned by [available slots](#reservation-available-slots--list) already use this format.

#### Payments

Services with `payment_mode` `deposit` or `full` (or `optional` when the booking sends `payment_choice: "pay_now"`) collect online payments through the organization's payment gateway. Reservations created through the API (`source` other than `manual`) for those services start as `status: "awaiting_payment"` with `payment_status: "pending"` and `payment_expires_at` = now + the service `payment_hold_minutes`; the create response then also includes `pay_url` (link to send to the customer), `payment_required` and `payment_unavailable_reason`. Reservations with `source: "manual"` are only held for payment when the body includes `"collect_payment": true`. When the payment arrives the reservation becomes `confirmed` (or `pending` when the service does not auto-confirm) and `payment_status` becomes `deposit_paid` or `paid`. When the organization cannot collect online (no active gateway, unsupported currency) the reservation is created normally with `payment_choice: "pay_later"` and `payment_unavailable_reason` explains why.

#### The reservation object

```json
{
  "id": 5001,
  "organization_id": 456,
  "service_id": 12,
  "contact_id": 9001,
  "party_size": 2,
  "start_datetime": "2026-04-25T15:00:00.000Z",
  "end_datetime": "2026-04-25T16:00:00.000Z",
  "status": "confirmed",
  "source": "api",
  "conversation_id": null,
  "deal_id": null,
  "company_id": null,
  "estimate_id": null,
  "invoice_id": null,
  "google_meet_link": null,
  "confirmation_sent_at": "2026-04-20T14:02:11.000Z",
  "reminders_sent": [
    { "key": "24-hours-0", "sent_at": "2026-04-24T15:00:40.000Z" }
  ],
  "cancelled_at": null,
  "cancelled_by": null,
  "cancellation_reason": null,
  "customer_notes": "Window seat if possible",
  "internal_notes": null,
  "payment_status": "deposit_paid",
  "payment_amount": "150.00",
  "preferred_resource_id": null,
  "duration_minutes": null,
  "amount_total": 150,
  "amount_due_now": 45,
  "amount_paid": 45,
  "system_currency_id": 1,
  "payment_choice": "pay_now",
  "payment_expires_at": "2026-04-20T14:32:10.000Z",
  "payment_link_id": 7781,
  "needs_refund": false,
  "refunded_amount": null,
  "refunded_at": null,
  "created_by_user_id": 789,
  "custom_fields_by_key": { "dietary_notes": "Vegetarian" },
  "custom_fields_by_name": { "Dietary notes": "Vegetarian" },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 31,
      "custom_field_key": "dietary_notes",
      "custom_field_name": "Dietary notes",
      "custom_field_value": "Vegetarian"
    }
  ],
  "created_at": "2026-04-20T14:02:10.000Z",
  "updated_at": "2026-04-24T15:00:40.000Z",
  "deleted_at": null,
  "service": {
    "id": 12,
    "name": "Consultation",
    "duration_minutes": 60,
    "timezone": "America/Bogota"
  },
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+15551234567"
  },
  "assigned_resources": [
    {
      "id": 3301,
      "reservation_id": 5001,
      "resource_id": 88,
      "status": "assigned",
      "reassigned_from_resource_id": null,
      "reassigned_reason": null,
      "capacity_used": 1,
      "resource": { "id": 88, "name": "Room A", "resource_type": "room", "capacity": 4 }
    }
  ]
}
```

`service`, `contact` and `assigned_resources` are joined on every read and write response; they are not columns and cannot be written. `service` is the full [service object](#reservation-services) and `resource` the full [resource object](#reservation-resources) (shortened above).

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization that owns the reservation. Required on create; must be the API key's organization. |
| `service_id` | integer | [Reservation service](#reservation-services) booked. Required on create. |
| `contact_id` | integer | [Contact](#contacts) the reservation is for. Required on create. |
| `party_size` | integer | Number of people. Minimum `1`, default `1`. Cannot exceed the service `max_party_size`. |
| `start_datetime` | string (date-time) | Start, as service wall-clock time (see above). Required on create. |
| `end_datetime` | string (date-time) | End. Computed from `start_datetime` + service `duration_minutes` when omitted on create, and recalculated whenever `start_datetime` or `service_id` changes. |
| `status` | string | One of `pending`, `confirmed`, `awaiting_payment`, `cancelled`, `completed`, `no_show`. Default `pending`; forced to `confirmed` on create when the service has `auto_confirm: true`. `awaiting_payment` is set by the server when the booking must be paid online first (see [Payments](#payments)): it holds the slot until `payment_expires_at`, then becomes `cancelled` with `cancellation_reason: "payment_expired"`. |
| `source` | string | Where the booking came from: `manual`, `whatsapp_ai`, `instagram_ai`, `webchat`, `public_link`, `api`, `automation` (automations). Default `manual`. |
| `conversation_id` | integer \| null | [Conversation](#conversations) where the booking originated. |
| `deal_id` | integer \| null | Related [deal](#deals). |
| `company_id` | integer \| null | Related [company](#companies). |
| `estimate_id` | integer \| null | Related estimate. |
| `invoice_id` | integer \| null | Related invoice. |
| `google_meet_link` | string \| null | Video-call link. Included in the confirmation and reminder emails when set. The API does not generate it. |
| `confirmation_sent_at` | string (date-time) \| null | Read-only in practice. Set when the confirmation email is sent to the contact. |
| `reminders_sent` | array | Read-only in practice. Reminder emails already sent, as `{ "key", "sent_at" }` items. Reset to `[]` when `start_datetime` changes so reminders are sent again for the new time. |
| `cancelled_at` | string (date-time) \| null | When it was cancelled. Not set automatically: send it together with `status: "cancelled"`. |
| `cancelled_by` | string \| null | One of `customer`, `organization`, `system`. |
| `cancellation_reason` | string \| null | Free-text cancellation reason. |
| `customer_notes` | string \| null | Notes from the customer. |
| `internal_notes` | string \| null | Internal staff notes. |
| `payment_status` | string | One of `none`, `not_required`, `pending`, `deposit_paid`, `paid`, `partially_refunded`, `refunded`, `expired` (`none` and `not_required` mean no payment is expected). Set by the server for services with online payments: `pending` while something is due, `deposit_paid` / `paid` after payment, `expired` when an unpaid hold expires. When omitted on create for a service without payments the stored default is `not_required`. |
| `payment_amount` | string (decimal) \| null | Amount paid or due (returned as a decimal string, for example `"150.00"`). Minimum `0`. Used as the purchase amount when loyalty points are awarded on completion. |
| `preferred_resource_id` | integer \| null | [Resource](#reservation-resources) the customer asked for. On create, availability is checked only against this resource. |
| `duration_minutes` | integer \| null | Length chosen by the customer for services with `duration_mode: "flexible"`; must be one of the service `duration_options`. `null` = the service `duration_minutes`. Used for `end_datetime` and the price. |
| `amount_total` | number \| null | Read-only in practice. Price of the booking computed from the service `price` and `pricing_unit` (per booking, × `party_size` or × hours). Recomputed when the service, party size or duration change while nothing has been paid. `null` when the service has no price. |
| `amount_due_now` | number \| null | Read-only in practice. What the online payment charges: the deposit (`payment_mode: "deposit"`) or the total (`full`, or `optional` with `payment_choice: "pay_now"`). |
| `amount_paid` | number | Read-only in practice. Total paid so far, from payment links and payments recorded in the app. Default `0`. |
| `system_currency_id` | integer \| null | Read-only. Currency of the amounts (the service currency). |
| `payment_choice` | string \| null | `pay_now` or `pay_later`. For services with `payment_mode: "optional"` it decides whether the customer pays online now; also set to `pay_later` when online payment is not available. |
| `payment_expires_at` | string (date-time) \| null | Read-only. Real UTC time (not wall-clock) until which an `awaiting_payment` booking holds its slot. |
| `payment_link_id` | integer \| null | Read-only. Payment link created for the online payment. |
| `needs_refund` | boolean | Read-only in practice. `true` when a paid booking was cancelled by the customer, or a payment arrived after the slot was taken, and the money should be returned. Default `false`. |
| `refunded_amount` | number \| null | Read-only in practice. Amount marked as refunded in the app (bookkeeping only, no gateway refund). |
| `refunded_at` | string (date-time) \| null | Read-only in practice. When the refund was recorded. |
| `created_by_user_id` | integer \| null | Read-only. User who created it; with an API key, the user the key belongs to. |
| `custom_fields_by_key` | object | Reservation custom field values keyed by field `key` (fields with `entity_type: "reservation"`). On update, keys are merged into the existing values; send `null` to clear a key. Unknown keys return `400`. |
| `custom_fields_by_name` | object | Read-only. Same values keyed by field name. Derived from `custom_fields_by_key`. |
| `custom_fields_meta_data` | array | Read-only. One item per value: `custom_field_id`, `custom_field_key`, `custom_field_name`, `custom_field_value`. Derived from `custom_fields_by_key`. |
| `created_at` | string (date-time) | Read-only. Creation time. |
| `updated_at` | string (date-time) | Read-only. Last update time. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the reservation is deleted; deleted reservations are not returned. |

#### Side effects

- **Create:** the slot is validated (see [Create a reservation](#reservations--create)), linked resources are assigned (`assigned_resources`), the confirmation email is sent to the contact and a notification to staff resources linked to a user (both on by default, configurable in the organization's reservation settings), and **New reservation** automations run.
- **Update:** **Reservation updated** automations run; moving to `completed` awards loyalty points or stamps to the contact when the organization has an active loyalty program.
- **Reminders:** reminder emails are sent automatically before `start_datetime` according to the organization's reservation settings and recorded in `reminders_sent`.
- No email is sent for reservations in `cancelled` or `no_show` status.

#### Related

- [Reservation services](#reservation-services)
- [Reservation available slots](#reservation-available-slots)
- [Reservation resources](#reservation-resources)
- [Reservation booking links](#reservation-booking-links)
- [Contacts](#contacts)

<a id="reservations--list"></a>

### List reservations

Source: https://www.achieveapex.com/docs/api-reference/reservations/list

Returns a paginated list of the organization's reservations, with `service`, `contact` and `assigned_resources` joined.

#### Endpoint

`GET /reservations`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | Filter by status. Use `status[$in][]=pending&status[$in][]=confirmed` for several, or `status[$ne]=cancelled`. |
| `service_id` | integer | No | Only reservations of this service. |
| `contact_id` | integer | No | Only reservations of this contact. |
| `deal_id`, `company_id`, `conversation_id` | integer | No | Only reservations linked to this record. |
| `source` | string | No | One of `manual`, `whatsapp_ai`, `instagram_ai`, `webchat`, `public_link`, `api`, `automation`. |
| `date_from` | string (`YYYY-MM-DD`) | No | Reservations starting on or after this date (service wall-clock time). |
| `date_to` | string (`YYYY-MM-DD`) | No | Reservations starting on or before this date (inclusive, whole day). |
| `start_datetime` | string | No | Range filter with operators, e.g. `start_datetime[$gte]=2026-04-20T00:00:00.000Z`. |
| `searchTerm` | string | No | Case-insensitive text search over the contact's first name, last name, full name and email, the service name, `customer_notes` and `internal_notes`. When used without `$sort`, results are sorted by `start_datetime` ascending. |
| `$limit` | integer | No | Page size. Default `10`, maximum `50`. |
| `$skip` | integer | No | Number of records to skip. |
| `$sort[field]` | `1` \| `-1` | No | Sort, e.g. `$sort[start_datetime]=1`. |
| `$select[]` | string | No | Return only these fields. |

Any other field of the [reservation object](#reservations) can be used as a filter. Results are limited to the API key's organization automatically.

#### Request

```bash
curl -G https://integrations.achieveapex.com/reservations \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'date_from=2026-04-20' \
  --data-urlencode 'date_to=2026-04-26' \
  --data-urlencode 'status[$in][]=pending' \
  --data-urlencode 'status[$in][]=confirmed' \
  --data-urlencode '$limit=50' \
  --data-urlencode '$sort[start_datetime]=1'
```

Search by customer name or email:

```bash
curl -G https://integrations.achieveapex.com/reservations \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'searchTerm=jane@example.com' \
  --data-urlencode '$limit=25'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 5001,
      "organization_id": 456,
      "service_id": 12,
      "contact_id": 9001,
      "party_size": 2,
      "start_datetime": "2026-04-25T15:00:00.000Z",
      "end_datetime": "2026-04-25T16:00:00.000Z",
      "status": "confirmed",
      "source": "api",
      "customer_notes": "Window seat if possible",
      "internal_notes": null,
      "payment_status": "not_required",
      "payment_amount": null,
      "preferred_resource_id": null,
      "custom_fields_by_key": {},
      "created_at": "2026-04-20T14:02:10.000Z",
      "updated_at": "2026-04-20T14:02:11.000Z",
      "deleted_at": null,
      "service": { "id": 12, "name": "Consultation", "duration_minutes": 60 },
      "contact": {
        "id": 9001,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "phone": "+15551234567"
      },
      "assigned_resources": []
    }
  ]
}
```

Each item contains every field of the [reservation object](#reservations) (shortened above).

<a id="reservations--get"></a>

### Get a reservation

Source: https://www.achieveapex.com/docs/api-reference/reservations/get

Returns one reservation by ID, with `service`, `contact` and `assigned_resources` joined.

#### Endpoint

`GET /reservations/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/reservations/5001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 5001,
  "organization_id": 456,
  "service_id": 12,
  "contact_id": 9001,
  "party_size": 2,
  "start_datetime": "2026-04-25T15:00:00.000Z",
  "end_datetime": "2026-04-25T16:00:00.000Z",
  "status": "confirmed",
  "source": "api",
  "conversation_id": null,
  "deal_id": null,
  "company_id": null,
  "estimate_id": null,
  "invoice_id": null,
  "google_meet_link": null,
  "confirmation_sent_at": "2026-04-20T14:02:11.000Z",
  "reminders_sent": [],
  "cancelled_at": null,
  "cancelled_by": null,
  "cancellation_reason": null,
  "customer_notes": "Window seat if possible",
  "internal_notes": null,
  "payment_status": "not_required",
  "payment_amount": null,
  "preferred_resource_id": null,
  "created_by_user_id": 789,
  "custom_fields_by_key": { "dietary_notes": "Vegetarian" },
  "custom_fields_by_name": { "Dietary notes": "Vegetarian" },
  "custom_fields_meta_data": [
    {
      "custom_field_id": 31,
      "custom_field_key": "dietary_notes",
      "custom_field_name": "Dietary notes",
      "custom_field_value": "Vegetarian"
    }
  ],
  "created_at": "2026-04-20T14:02:10.000Z",
  "updated_at": "2026-04-20T14:02:11.000Z",
  "deleted_at": null,
  "service": { "id": 12, "name": "Consultation", "duration_minutes": 60 },
  "contact": {
    "id": 9001,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+15551234567"
  },
  "assigned_resources": []
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No reservation with that ID in your organization, or it was deleted. |

<a id="reservations--create"></a>

### Create a reservation

Source: https://www.achieveapex.com/docs/api-reference/reservations/create

Books a contact into a service. Pick a slot from [available slots](#reservation-available-slots--list) and send its `start_datetime`; the end time is computed from the service duration.

#### Endpoint

`POST /reservations`

#### Body

| Field | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID (the API key's organization). |
| `service_id` | integer | Yes | [Reservation service](#reservation-services) to book. Must be active. |
| `contact_id` | integer | Yes | [Contact](#contacts) the booking is for. |
| `start_datetime` | string (date-time) | Yes | Start, as service wall-clock time (see [date and time format](#reservations)). |
| `end_datetime` | string (date-time) | No | Computed from the service `duration_minutes` when omitted. |
| `party_size` | integer | No | Default `1`. Must be between the service `min_party_size` and `max_party_size`. |
| `duration_minutes` | integer | No | For services with `duration_mode: "flexible"`: one of the service `duration_options`. Sets `end_datetime` and the price. |
| `payment_choice` | string | No | `pay_now` or `pay_later`. For services with `payment_mode: "optional"`: `pay_now` holds the slot until the customer pays online. |
| `collect_payment` | boolean | No | Only for `source: "manual"`: hold the booking as `awaiting_payment` and create a payment link, like customer bookings. Not stored. |
| `status` | string | No | `pending`, `confirmed`, `cancelled`, `completed` or `no_show`. Ignored (set to `confirmed`) when the service has `auto_confirm: true`, and replaced by `awaiting_payment` when the booking must be paid online first (see [payments](#reservations)). |
| `source` | string | No | `manual`, `whatsapp_ai`, `instagram_ai`, `webchat`, `public_link`, `api` or `automation`. Default `manual`. |
| `preferred_resource_id` | integer | No | Book on this [resource](#reservation-resources). |
| `customer_notes`, `internal_notes` | string | No | Notes. |
| `conversation_id`, `deal_id`, `company_id`, `estimate_id`, `invoice_id` | integer | No | Related records. |
| `google_meet_link` | string | No | Video-call link to include in emails. |
| `payment_status` | string | No | `none`, `pending`, `paid` or `refunded`. Stored as `not_required` when omitted; set by the server for services with online payments. |
| `payment_amount` | number | No | Amount, minimum `0`. |
| `custom_fields_by_key` | object | No | Reservation custom field values keyed by field `key`. |

See the [reservation object](#reservations) for every field.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/reservations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "service_id": 12,
    "contact_id": 9001,
    "party_size": 2,
    "start_datetime": "2026-04-25T15:00:00.000Z",
    "source": "api",
    "customer_notes": "Window seat if possible",
    "custom_fields_by_key": { "dietary_notes": "Vegetarian" }
  }'
```

#### Response

Returns the created [reservation object](#reservations) with `end_datetime`, `status`, `service`, `contact` and `assigned_resources`. For services with online payments the create response also has `pay_url` (payment link to send to the customer, or `null`), `payment_required` and `payment_unavailable_reason` (`null`, or why the payment could not be requested online: `no_active_gateway`, `gateway_inactive`, `currency_not_supported`, `no_currency`, `no_contact`, `link_failed`, `error`). These three are only in the create response.

```json
{
  "id": 5001,
  "organization_id": 456,
  "service_id": 12,
  "contact_id": 9001,
  "party_size": 2,
  "start_datetime": "2026-04-25T15:00:00.000Z",
  "end_datetime": "2026-04-25T16:00:00.000Z",
  "status": "confirmed",
  "source": "api",
  "customer_notes": "Window seat if possible",
  "payment_status": "not_required",
  "custom_fields_by_key": { "dietary_notes": "Vegetarian" },
  "created_at": "2026-04-20T14:02:10.000Z",
  "updated_at": "2026-04-20T14:02:10.000Z",
  "deleted_at": null,
  "service": { "id": 12, "name": "Consultation", "duration_minutes": 60 },
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "+15551234567" },
  "assigned_resources": [
    { "id": 3301, "reservation_id": 5001, "resource_id": 88, "status": "assigned", "capacity_used": 1, "resource": { "id": 88, "name": "Room A" } }
  ]
}
```

#### Validation

Before saving, the API checks, in the service's `timezone`:

- The service is active and `party_size` ≤ `max_party_size`.
- When `min_advance_hours` > 0: the date is not in the past and, for today, the start is at least `min_advance_hours` away.
- When `max_advance_days` > 0: the date is at most `max_advance_days` ahead.
- When `max_daily_bookings` is set: fewer than that many `pending`/`confirmed` reservations exist for the service that day.
- When `capacity_mode` is `per_slot`: fewer than `slot_capacity` `pending`/`confirmed` reservations overlap the time (only those on `preferred_resource_id` when it is sent).
- For each [linked resource](#reservation-service-resources): the resource has a weekly [availability](#reservation-resource-availability) block covering the time on that weekday, no `blocked` [exception](#reservation-resource-exceptions) that day, and enough free `capacity`. `required` resources must pass; `optional` ones are skipped when busy; `any_available` picks any active resource of the same `resource_type`.

Resources that pass are assigned to the reservation and returned in `assigned_resources`.

#### Side effects

- Sends the confirmation email to the contact (sets `confirmation_sent_at`) and a notification to staff resources linked to a user, when enabled in the organization's reservation settings (both on by default). Not sent for `cancelled` or `no_show`.
- Runs the organization's **New reservation** automations.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Missing required field, invalid enum, inactive service, party size too large, outside the advance-booking window, daily limit reached, slot fully booked, a required resource unavailable, or unknown custom field key. The message says which. |
| `403 Forbidden` | `organization_id` is not the API key's organization. |

<a id="reservations--update"></a>

### Update a reservation

Source: https://www.achieveapex.com/docs/api-reference/reservations/update

Partially updates a reservation: reschedule, change status (confirm, complete, cancel, no-show), notes, links or custom fields. Only the fields you send change.

#### Endpoint

`PATCH /reservations/:id`

#### Body

Any writable field of the [reservation object](#reservations). Common ones:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | `pending`, `confirmed`, `cancelled`, `completed` or `no_show`. Confirming or cancelling also creates or removes the booking's events in connected calendars. |
| `start_datetime` | string (date-time) | No | New start. Availability is checked again (the reservation itself is excluded) and the request fails with `400` when the new time is taken. `end_datetime` is recalculated from the service duration, and `reminders_sent` is reset so reminders go out again. |
| `service_id` | integer | No | Change the service; `end_datetime` is recalculated. |
| `party_size` | integer | No | Number of people. |
| `duration_minutes` | integer | No | New length for services with `duration_mode: "flexible"` (one of `duration_options`). |
| `cancelled_at` | string (date-time) | No | Send with `status: "cancelled"`; it is not set automatically. |
| `cancelled_by` | string | No | `customer`, `organization` or `system`. |
| `cancellation_reason` | string | No | Free text. |
| `customer_notes`, `internal_notes` | string \| null | No | Notes. |
| `payment_status` | string | No | `none`, `pending`, `paid` or `refunded`. |
| `payment_amount` | number \| null | No | Amount, minimum `0`. |
| `preferred_resource_id` | integer \| null | No | Preferred resource. |
| `contact_id`, `deal_id`, `company_id`, `conversation_id`, `estimate_id`, `invoice_id` | integer \| null | No | Related records. |
| `google_meet_link` | string \| null | No | Video-call link used in emails. |
| `custom_fields_by_key` | object | No | Merged into existing values; send a key with `null` to clear it. |

Updating does **not** re-run the slot and capacity checks done on create, and does not reassign resources.

#### Request

Reschedule:

```bash
curl -X PATCH https://integrations.achieveapex.com/reservations/5001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_datetime": "2026-04-26T14:00:00.000Z",
    "internal_notes": "Moved at customer request"
  }'
```

Cancel:

```bash
curl -X PATCH https://integrations.achieveapex.com/reservations/5001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled",
    "cancelled_at": "2026-04-24T18:00:00.000Z",
    "cancelled_by": "organization",
    "cancellation_reason": "Staff unavailable"
  }'
```

Mark as completed:

```bash
curl -X PATCH https://integrations.achieveapex.com/reservations/5001 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "payment_amount": 150 }'
```

#### Response

Returns the updated [reservation object](#reservations), with `service`, `contact` and `assigned_resources`.

```json
{
  "id": 5001,
  "organization_id": 456,
  "service_id": 12,
  "contact_id": 9001,
  "start_datetime": "2026-04-26T14:00:00.000Z",
  "end_datetime": "2026-04-26T15:00:00.000Z",
  "status": "confirmed",
  "reminders_sent": [],
  "internal_notes": "Moved at customer request",
  "updated_at": "2026-04-21T09:30:00.000Z",
  "service": { "id": 12, "name": "Consultation", "duration_minutes": 60 },
  "contact": { "id": 9001, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "phone": "+15551234567" },
  "assigned_resources": []
}
```

#### Side effects

- Runs the organization's **Reservation updated** automations.
- Changing `status` to `completed` awards loyalty points or stamps to the contact (once per reservation) when the organization has an active loyalty program; `payment_amount` counts as the purchase amount.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | Invalid field value or enum, or unknown custom field key. |
| `404 Not Found` | No reservation with that ID in your organization. |

<a id="reservations--delete"></a>

### Delete a reservation

Source: https://www.achieveapex.com/docs/api-reference/reservations/delete

Deletes a reservation. This is a soft delete: the record gets `deleted_at` and no longer appears in list or get. To keep the booking in history, [update](#reservations--update) its `status` to `cancelled` instead.

#### Endpoint

`DELETE /reservations/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/reservations/5001 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

Returns the deleted [reservation object](#reservations) with `deleted_at` set.

```json
{
  "id": 5001,
  "organization_id": 456,
  "service_id": 12,
  "contact_id": 9001,
  "status": "confirmed",
  "start_datetime": "2026-04-25T15:00:00.000Z",
  "end_datetime": "2026-04-25T16:00:00.000Z",
  "deleted_at": "2026-04-22T10:00:00.000Z"
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | No reservation with that ID in your organization. |

---

## Support Tickets

<a id="support-tickets"></a>

### Support Tickets overview

Source: https://www.achieveapex.com/docs/api-reference/support-tickets

A support ticket is an email thread with a customer in your helpdesk inbox (Gmail or Outlook). Use it to list, create, assign, prioritize and close tickets, move them through ticket pipelines and set their custom fields.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/support-tickets` | [List tickets](#support-tickets--list) |
| `GET` | `/support-tickets/:id` | [Get a ticket](#support-tickets--get) |
| `POST` | `/support-tickets` | [Create a ticket](#support-tickets--create) |
| `PATCH` | `/support-tickets/:id` | [Update a ticket](#support-tickets--update) |
| `DELETE` | `/support-tickets/:id` | [Delete a ticket](#support-tickets--delete) |

#### The support ticket object

```json
{
  "id": 123,
  "organization_id": 456,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@acme.com",
  "contact_id": 88001,
  "meta_contact_email": "maria@example.com",
  "meta_contact_first_name": "Maria",
  "meta_contact_last_name": "Lopez",
  "reference_number": null,
  "subject": "Cannot access my account",
  "status": "open",
  "priority": "high",
  "tags": [{ "id": 3, "name": "login", "color": "#3B82F6" }],
  "assigned_user_id": 12,
  "assigned_ai_assistant_id": null,
  "thread_id": "18d4f2c9a1b2c3d4",
  "last_message_at": "2026-02-10T10:45:20.000Z",
  "last_message_received": "2026-02-10T10:45:20.000Z",
  "last_message_sent": "2026-02-10T09:00:00.000Z",
  "last_message_system": "2026-02-10T08:00:00.000Z",
  "unread_count": 1,
  "is_unread": true,
  "handoff_reason": null,
  "next_follow_up_rule_id": null,
  "next_follow_up_date_time": null,
  "follow_up_count": 0,
  "pipeline_id": 20,
  "pipeline_stage_id": 71,
  "custom_fields_by_key": { "order_number": "A-1043" },
  "custom_fields_by_name": { "Order number": "A-1043" },
  "conversation_summary": null,
  "conversation_summary_updated_at": null,
  "created_at": "2026-02-10T08:00:00.000Z",
  "updated_at": "2026-02-10T10:45:20.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. |
| `organization_id` | integer | Organization. Required on create. |
| `inbox_channel_id` | integer | Read-only on create. Helpdesk inbox (email account) of the ticket. Set to the organization's active inbox. |
| `channel` | string | Read-only. `gmail` or `outlook`, from the inbox. |
| `meta_inbox_channel_email` | string \| null | Read-only. Email address of the inbox. |
| `contact_id` | integer \| null | [Contact](#contacts) who opened the ticket. |
| `meta_contact_email` | string \| null | Contact email, copied from the contact on create. |
| `meta_contact_first_name` / `meta_contact_last_name` | string \| null | Contact name, copied from the contact on create. |
| `reference_number` | string \| null | Your own reference for the ticket. |
| `subject` | string | Ticket subject. Required on create. |
| `status` | string | `open`, `pending`, `waiting_customer`, `done` or `closed`. Default `open`. |
| `priority` | string | `low`, `medium`, `high` or `urgent`. Default `medium`. |
| `tags` | array | Tags: `{ "id", "name", "color" }`. Default `[]`. |
| `assigned_user_id` | integer \| null | Human owner. Changing it notifies the new owner. |
| `assigned_ai_assistant_id` | integer \| null | AI assistant answering the ticket. |
| `thread_id` | string | Read-only. Email thread ID in the mailbox (`created-<timestamp>` for tickets created through the API). |
| `last_message_at` | string (date-time) | Read-only. Time of the last message. |
| `last_message_received` / `last_message_sent` / `last_message_system` | string (date-time) | Read-only. Time of the last incoming, outgoing and system message. |
| `unread_count` | integer | Unread incoming messages. Default `0`. |
| `is_unread` | boolean | Marked unread in the inbox. Default `false`. |
| `handoff_reason` | string \| null | Why the AI assistant handed the ticket to a human. |
| `next_follow_up_rule_id` | string \| null | Read-only. AI follow-up rule scheduled next. |
| `next_follow_up_date_time` | string \| null | When the next AI follow-up is scheduled. Setting it schedules the follow-up. |
| `follow_up_count` | integer | Read-only. AI follow-ups sent. Default `0`. |
| `pipeline_id` | integer \| null | Ticket [pipeline](#pipelines) (type `ticket`). |
| `pipeline_stage_id` | integer \| null | [Stage](#pipeline-stages) inside `pipeline_id`. |
| `custom_fields_by_key` | object | Custom field values by field key. Write custom fields here; values are validated against the field type. |
| `custom_fields_by_name` | object | Read-only. Same values keyed by field name. |
| `conversation_summary` | string \| null | Read-only. AI summary of older messages. |
| `conversation_summary_updated_at` | string (date-time) \| null | Read-only. |
| `created_at` | string (date-time) | Read-only. |
| `updated_at` | string (date-time) | Read-only. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the ticket is deleted. |

Reads are limited to your API key's organization. Member roles with limited ticket permissions only see and edit what their role allows.

#### Related

- [Contacts](#contacts)
- [Pipelines](#pipelines) and [Pipeline stages](#pipeline-stages) (type `ticket`)
- [Upload URLs](#s3-url-signing) (type `support-ticket-file`)
- [Errors](#support-tickets--errors)

<a id="support-tickets--list"></a>

### List support tickets

Source: https://www.achieveapex.com/docs/api-reference/support-tickets/list

List the support tickets of your organization with filters and pagination.

#### Endpoint

`GET /support-tickets`

#### Query parameters

Any [ticket field](#support-tickets) can be used as a filter with the [standard operators](#requests).

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization. Results are always limited to your API key's organization. |
| `status` | string | No | `open`, `pending`, `waiting_customer`, `done` or `closed`. Several: `status[$in][]=open&status[$in][]=pending`. |
| `priority` | string | No | `low`, `medium`, `high` or `urgent`. |
| `assigned_user_id` | integer \| null | No | Human owner. `null` = unassigned. |
| `assigned_ai_assistant_id` | integer \| null | No | AI assistant. |
| `contact_id` | integer | No | Tickets of one contact. |
| `inbox_channel_id` | integer | No | Tickets of one inbox. |
| `pipeline_id` / `pipeline_stage_id` | integer | No | Ticket pipeline and stage. |
| `is_unread` | boolean | No | `true` = unread tickets. |
| `last_message_at[$gte]` | string (date-time) | No | Date range (also `$lte`, and on `created_at`). |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[last_message_at]` | `1` \| `-1` | No | Sort order. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/support-tickets \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'status[$in][]=open' \
  --data-urlencode 'status[$in][]=pending' \
  --data-urlencode 'priority=high' \
  --data-urlencode '$limit=25' \
  --data-urlencode '$sort[last_message_at]=-1'
```

#### Response

```json
{
  "total": 15,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "organization_id": 456,
      "inbox_channel_id": 5,
      "channel": "gmail",
      "contact_id": 88001,
      "subject": "Cannot access my account",
      "status": "open",
      "priority": "high",
      "tags": [],
      "assigned_user_id": 12,
      "assigned_ai_assistant_id": null,
      "last_message_at": "2026-02-10T10:45:20.000Z",
      "is_unread": true,
      "created_at": "2026-02-10T08:00:00.000Z",
      "updated_at": "2026-02-10T10:45:20.000Z"
    }
  ]
}
```

Each item is a full [support ticket object](#support-tickets) (shortened here).

<a id="support-tickets--get"></a>

### Get a support ticket

Source: https://www.achieveapex.com/docs/api-reference/support-tickets/get

Retrieve one support ticket by ID. The response also includes the ticket's contact.

#### Endpoint

`GET /support-tickets/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/support-tickets/123 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 123,
  "organization_id": 456,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@acme.com",
  "contact_id": 88001,
  "meta_contact_email": "maria@example.com",
  "meta_contact_first_name": "Maria",
  "meta_contact_last_name": "Lopez",
  "subject": "Cannot access my account",
  "status": "open",
  "priority": "high",
  "tags": [],
  "assigned_user_id": 12,
  "assigned_ai_assistant_id": null,
  "thread_id": "18d4f2c9a1b2c3d4",
  "last_message_at": "2026-02-10T10:45:20.000Z",
  "pipeline_id": 20,
  "pipeline_stage_id": 71,
  "custom_fields_by_key": {},
  "custom_fields_by_name": {},
  "created_at": "2026-02-10T08:00:00.000Z",
  "updated_at": "2026-02-10T10:45:20.000Z",
  "deleted_at": null,
  "contact": {
    "id": 88001,
    "organization_id": 456,
    "first_name": "Maria",
    "last_name": "Lopez",
    "email": "maria@example.com"
  }
}
```

| Extra field | Description |
|---|---|
| `contact` | The ticket's [contact](#contacts) record (all contact columns, shortened here), or `null` if it was deleted. Only present when `contact_id` is set. |

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The ID does not exist, was deleted, or belongs to an organization your API key cannot access. |

<a id="support-tickets--create"></a>

### Create a support ticket

Source: https://www.achieveapex.com/docs/api-reference/support-tickets/create

Create a support ticket in your helpdesk. The organization needs an active helpdesk inbox (Gmail or Outlook): the ticket is attached to it automatically.

#### Endpoint

`POST /support-tickets`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | Yes | Your organization ID. |
| `subject` | string | Yes | Ticket subject. |
| `contact_id` | integer | No | Contact who opened the ticket. Their email and name are copied to `meta_contact_email`, `meta_contact_first_name`, `meta_contact_last_name`. |
| `status` | string | No | `open` (default), `pending`, `waiting_customer`, `done` or `closed`. |
| `priority` | string | No | `low`, `medium` (default), `high` or `urgent`. |
| `tags` | array | No | Tags: `[{ "id": 3, "name": "login", "color": "#3B82F6" }]`. |
| `reference_number` | string | No | Your own reference. |
| `assigned_user_id` | integer | No | Human owner (notified). |
| `assigned_ai_assistant_id` | integer | No | AI assistant. |
| `pipeline_id` / `pipeline_stage_id` | integer | No | Ticket pipeline and stage. |
| `custom_fields_by_key` | object | No | Custom field values by key. |

`inbox_channel_id`, `channel`, `meta_inbox_channel_email`, `thread_id` and `last_message_at` are set by the server from the organization's active inbox; values you send are replaced.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/support-tickets \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "contact_id": 88001,
    "subject": "Need help with integration",
    "priority": "medium",
    "custom_fields_by_key": { "order_number": "A-1043" }
  }'
```

#### Response

The created [support ticket](#support-tickets):

```json
{
  "id": 125,
  "organization_id": 456,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@acme.com",
  "contact_id": 88001,
  "meta_contact_email": "maria@example.com",
  "meta_contact_first_name": "Maria",
  "meta_contact_last_name": "Lopez",
  "subject": "Need help with integration",
  "status": "open",
  "priority": "medium",
  "tags": [],
  "thread_id": "created-1770718353215",
  "last_message_at": "2026-02-10T09:12:33.215Z",
  "custom_fields_by_key": { "order_number": "A-1043" },
  "custom_fields_by_name": { "Order number": "A-1043" },
  "created_at": "2026-02-10T09:12:33.215Z",
  "updated_at": "2026-02-10T09:12:33.215Z",
  "deleted_at": null
}
```

Creating a ticket does not send an email; reply from the helpdesk inbox in the app.

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | An unknown field, an invalid `status` / `priority`, an invalid custom field value, or a pipeline you cannot access. |
| `500` | `organization_id` missing, `subject` missing, or the organization has no active helpdesk inbox. |

<a id="support-tickets--update"></a>

### Update a support ticket

Source: https://www.achieveapex.com/docs/api-reference/support-tickets/update

Partially update a support ticket: status, priority, owner, AI assistant, tags, pipeline stage or custom fields. Send only the fields you want to change.

#### Endpoint

`PATCH /support-tickets/:id`

#### Body

Any writable [ticket field](#support-tickets). The common ones:

| Name | Type | Description |
|---|---|---|
| `status` | string | `open`, `pending`, `waiting_customer`, `done` or `closed`. |
| `priority` | string | `low`, `medium`, `high` or `urgent`. |
| `assigned_user_id` | integer \| null | Human owner. The new owner is notified. |
| `assigned_ai_assistant_id` | integer \| null | AI assistant. |
| `tags` | array | Full list of tags `{ "id", "name", "color" }`. |
| `pipeline_id` / `pipeline_stage_id` | integer \| null | Ticket pipeline and stage. |
| `custom_fields_by_key` | object | Custom field values by key; `null` clears a value. |
| `is_unread` / `unread_count` | boolean / integer | Mark read or unread. |
| `next_follow_up_date_time` | string (date-time) | Schedules the next AI follow-up. |

#### Request

```bash
curl -X PATCH https://integrations.achieveapex.com/support-tickets/125 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "pending",
    "priority": "high",
    "assigned_user_id": 12
  }'
```

#### Response

The updated [support ticket](#support-tickets):

```json
{
  "id": 125,
  "organization_id": 456,
  "subject": "Need help with integration",
  "status": "pending",
  "priority": "high",
  "assigned_user_id": 12,
  "updated_at": "2026-02-10T09:30:45.127Z"
}
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | An unknown field, an invalid enum value, an invalid custom field value, or a pipeline you cannot access. |
| `403 Forbidden` | Your API key's role cannot edit this ticket. |
| `404 Not Found` | The ticket does not exist or was deleted. |

<a id="support-tickets--delete"></a>

### Delete a support ticket

Source: https://www.achieveapex.com/docs/api-reference/support-tickets/delete

Delete a support ticket. This is a soft delete: the ticket gets `deleted_at` and no longer appears in list or get responses. Its data is kept.

#### Endpoint

`DELETE /support-tickets/:id`

#### Request

```bash
curl -X DELETE https://integrations.achieveapex.com/support-tickets/125 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

The deleted [support ticket](#support-tickets) with `deleted_at` set:

```json
{
  "id": 125,
  "organization_id": 456,
  "subject": "Need help with integration",
  "status": "pending",
  "deleted_at": "2026-02-10T10:15:22.554Z"
}
```

#### Errors

| Status | When |
|---|---|
| `403 Forbidden` | Your API key's role cannot delete tickets. |
| `404 Not Found` | The ticket does not exist or was already deleted. |

<a id="support-tickets--errors"></a>

### Support ticket errors

Source: https://www.achieveapex.com/docs/api-reference/support-tickets/errors

Support ticket endpoints use the [standard error format](#errors). These are the cases specific to tickets.

| Status | Example message | When |
|---|---|---|
| `400 Bad Request` | `Invalid value for Priority level. Must be one of: ...` | A custom field value does not match its type or options. |
| `400 Bad Request` | `data/status must be equal to one of the allowed values` | Invalid `status` or `priority`, or an unknown field. |
| `403 Forbidden` | `Access denied: ...` | The API key's role has no permission for this action. Unauthenticated requests also return `403`. |
| `404 Not Found` | `No record found for id '999'` | The ticket does not exist, was deleted, or belongs to another organization. |
| `500` | `No active inbox channel found for this organization` | Creating a ticket when the organization has no active helpdesk inbox. |

```json
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
```

---

## Upload URLs

<a id="s3-url-signing"></a>

### Upload URLs overview

Source: https://www.achieveapex.com/docs/api-reference/s3-url-signing

Files are never sent through the API itself. Ask for a signed upload URL, `PUT` the file bytes to it, then save the returned key on the record that uses the file (a conversation file, product media, a custom field value...).

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/s3-url-signing` | [Create an upload URL](#s3-url-signing--create) |

#### Request fields

| Field | Type | Description |
|---|---|---|
| `type` | string | Required. What the file is for; decides where it is stored and which ID is required (table below). |
| `filename` | string | Required. Original file name. It is sanitized and prefixed with a timestamp. |
| `contentType` | string | MIME type of the file. Default `application/octet-stream`. The upload must use the same `Content-Type`. |
| `file_size` | integer | Size in bytes. |
| `organization_id` | integer | Organization, for types not tied to another record. |
| `conversation_id` | integer | Conversation, for `conversation-file`. |
| `contact_id` | integer | Contact, for `contact-avatar` and `crm-file`. |
| `company_id` | integer | Company, for `company-avatar` and `crm-file`. |
| `deal_id` | integer | Deal, for `crm-file`. |
| `product_id` | integer | Product, for `product-media`. |
| `ticket_id` | integer | Support ticket, for `support-ticket-file`. |
| `automation_id` | integer | Automation, for `automation-file`. |
| `estimate_id` | integer | Estimate, for `estimate-file`. |
| `invoice_id` | integer | Invoice, for `invoice-file`. |
| `contract_id` | integer | Contract, for `contract-document` and `contract-related-file`. |
| `entity_type` | string | For `custom-field-file`: `contact`, `company`, `deal`, `ticket`, `reservation`, `product`, `estimate` or `invoice`. |
| `entity_id` | integer | For `custom-field-file`: ID of that record. |
| `field_key` | string | For `custom-field-file`: key of the file custom field. |

#### Upload types

| `type` | Required fields | Used by |
|---|---|---|
| `conversation-file` | `conversation_id` | [Conversation files](#conversation-files--upload) and message attachments. |
| `conversation-predefined-message` | `organization_id` | Media of [predefined messages](#conversation-predefined-messages). |
| `whatsapp-template` | `organization_id` | Header media of WhatsApp templates. |
| `contact-avatar` | `contact_id` | Contact avatar. |
| `company-avatar` | `company_id` | Company avatar. |
| `crm-file` | one of `contact_id`, `deal_id`, `company_id` | Files attached to a contact, deal or company. |
| `product-media` | `product_id` | [Product media](#product-media--create). |
| `support-ticket-file` | `ticket_id` | Support ticket attachments. |
| `automation-file` | `automation_id` | Files used by automations. |
| `custom-field-file` | `entity_type`, `entity_id`, `field_key` | Values of file custom fields. |
| `estimate-file` / `invoice-file` | `estimate_id` / `invoice_id` | Estimate and invoice attachments. |
| `contract-document` / `contract-related-file` | `contract_id` | Contract files. |
| `organization-logo` | `organization_id` | Organization logo. |

The service also accepts types used only by the AchieveApex app (website builder, presentations, whiteboards, internal support chat and others); they are not part of the public API.

#### Related

- [Upload a conversation file](#conversation-files--upload)
- [Upload product media](#product-media--create)

<a id="s3-url-signing--create"></a>

### Create an upload URL

Source: https://www.achieveapex.com/docs/api-reference/s3-url-signing/create

Get a pre-signed URL to upload one file. The URL accepts a single `PUT` and expires after 1 hour.

#### Endpoint

`POST /s3-url-signing`

#### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `type` | string | Yes | Upload type, see [Upload types](#s3-url-signing). |
| `filename` | string | Yes | Original file name. |
| `contentType` | string | No | MIME type. Default `application/octet-stream`. |
| *record ID* | integer | Depends on `type` | e.g. `conversation_id` for `conversation-file`, `product_id` for `product-media`. |

Unknown fields are rejected with `400 Bad Request`.

#### Request

```bash
curl -X POST https://integrations.achieveapex.com/s3-url-signing \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "conversation-file",
    "filename": "invoice.pdf",
    "conversation_id": 5001,
    "contentType": "application/pdf"
  }'
```

#### Response

```json
{
  "signedUrl": "https://achieveapex-conversation-files.s3.amazonaws.com/org_456/conversation_5001/20260210T150000_invoice.pdf?X-Amz-Algorithm=...",
  "s3Path": "s3://achieveapex-conversation-files/org_456/conversation_5001/20260210T150000_invoice.pdf",
  "s3PathWithoutBucket": "org_456/conversation_5001/20260210T150000_invoice.pdf",
  "headers": { "Content-Type": "application/pdf" }
}
```

| Field | Description |
|---|---|
| `signedUrl` | URL to `PUT` the file to. |
| `s3Path` | Full `s3://bucket/key` path. Save it where the target resource asks for `s3_path`. |
| `s3PathWithoutBucket` | Storage key. Save it where the target resource asks for `s3_key`. |
| `headers` | Headers to send with the upload. |

#### Upload the file

```bash
curl -X PUT "SIGNED_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf
```

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `type` or `filename` missing, an unknown field, or the record ID the type needs is missing or not found. |

---

## WhatsApp numbers

<a id="whatsapp-channels"></a>

### WhatsApp numbers overview

Source: https://www.achieveapex.com/docs/api-reference/whatsapp-channels

A WhatsApp channel is one WhatsApp Business number connected to your organization. An organization can connect several numbers; each [conversation](#conversations) belongs to one of them (`whatsapp_channel_id`). Numbers are connected and removed in the AchieveApex app (Settings, WhatsApp) because connecting requires Meta's sign-in; the API reads them.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/whatsapp-channels` | [List WhatsApp numbers](#whatsapp-channels--list) |
| `GET` | `/whatsapp-channels/:id` | [Get a WhatsApp number](#whatsapp-channels--get) |

#### The WhatsApp channel object

```json
{
  "id": 12,
  "organization_id": 456,
  "status": "active",
  "label": "Ventas",
  "display_phone_number": "+57 300 1234567",
  "verified_name": "Acme Store",
  "is_default": false,
  "wa_ba_id": "104857600123456",
  "wa_phone_number_id": "109876543210987",
  "waba_name": "Acme",
  "waba_currency": "USD",
  "waba_timezone": "America/Bogota",
  "waba_verification_status": "verified",
  "message_template_namespace": "a1b2c3d4_e5f6_7890_abcd_ef1234567890",
  "business_name": "Acme SAS",
  "business_id": "998877665544332",
  "business_status": "verified",
  "business_verification_status": "verified",
  "can_send_message": "AVAILABLE",
  "quality_rating": "GREEN",
  "phone_quality_score": "GREEN",
  "code_verification_status": "VERIFIED",
  "phone_number_status": "CONNECTED",
  "registration_status": "registered",
  "wa_name_status": "APPROVED",
  "whatsapp_business_manager_messaging_limit": "TIER_1K",
  "throughput_level": "STANDARD",
  "webhook_status": "subscribed",
  "is_business_app_onboarding": false,
  "created_at": "2026-01-05T12:00:00.000Z",
  "updated_at": "2026-02-10T08:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

All fields are read-only through the API. Values marked "from Meta" are copied from the WhatsApp Business Platform when the number is connected or refreshed, and use Meta's values.

| Field | Type | Description |
|---|---|---|
| `id` | integer | Unique ID. This is the `whatsapp_channel_id` used by conversations and [Start a WhatsApp conversation](#conversations--initiate-whatsapp). |
| `organization_id` | integer | Organization. |
| `status` | string | `pending`, `active` or `inactive`. Only `active` numbers send messages. |
| `label` | string \| null | Internal name of the number (e.g. "Ventas"), max 100 characters. |
| `display_phone_number` | string \| null | Phone number as shown by WhatsApp. From Meta. |
| `verified_name` | string \| null | Business display name approved by WhatsApp. From Meta. |
| `is_default` | boolean | Legacy flag. When a request does not pick a number, the API uses the oldest active number (lowest `id`). |
| `wa_ba_id` | string \| null | WhatsApp Business Account (WABA) ID. Numbers of the same WABA share [templates](#whatsapp-channel-message-templates). From Meta. |
| `wa_phone_number_id` | string \| null | WhatsApp phone number ID. From Meta. |
| `waba_name` | string \| null | WABA name. From Meta. |
| `waba_currency` | string \| null | WABA billing currency. From Meta. |
| `waba_timezone` | string \| null | WABA time zone. From Meta. |
| `waba_verification_status` | string \| null | WABA verification status. From Meta. |
| `message_template_namespace` | string \| null | WABA template namespace. From Meta. |
| `business_name` | string \| null | Meta Business portfolio name. From Meta. |
| `business_id` | string \| null | Meta Business portfolio ID. From Meta. |
| `business_status` | string \| null | Business portfolio status. From Meta. |
| `business_verification_status` | string \| null | Business verification status. From Meta. |
| `can_send_message` | string \| null | Whether this number can send messages, from the number's own Meta health status: `AVAILABLE`, `LIMITED` (connected but restricted, e.g. display name not approved yet) or `BLOCKED`. |
| `quality_rating` | string \| null | Number quality rating (e.g. `GREEN`, `YELLOW`, `RED`). From Meta. |
| `phone_quality_score` | string \| null | Quality score of the number. From Meta. |
| `code_verification_status` | string \| null | Phone verification status. From Meta. |
| `phone_number_status` | string \| null | Number status (e.g. `CONNECTED`). From Meta. |
| `registration_status` | string \| null | Cloud API registration status of the number. |
| `wa_name_status` | string \| null | Display name review status. From Meta. |
| `whatsapp_business_manager_messaging_limit` | string \| null | Daily conversation limit tier. From Meta. |
| `throughput_level` | string \| null | Messages-per-second level. From Meta. |
| `webhook_status` | string \| null | Status of the webhook subscription that delivers incoming messages. |
| `is_business_app_onboarding` | boolean \| null | The number was connected while staying on the WhatsApp Business app (coexistence). |
| `created_at` | string (date-time) | When the number was connected. |
| `updated_at` | string (date-time) | Last update. |
| `deleted_at` | string (date-time) \| null | Set when the number was removed. |

Access tokens and registration PINs are never returned.

<a id="whatsapp-channels--list"></a>

### List WhatsApp numbers

Source: https://www.achieveapex.com/docs/api-reference/whatsapp-channels/list

List the WhatsApp numbers connected to your organization, for example to pick the `whatsapp_channel_id` that [starts a conversation](#conversations--initiate-whatsapp).

#### Endpoint

`GET /whatsapp-channels`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization. Results are always limited to your API key's organization. |
| `status` | string | No | `active` returns only numbers that can send. Also `pending`, `inactive`. |
| `wa_ba_id` | string | No | Numbers of one WhatsApp Business Account. |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[id]` | `1` \| `-1` | No | `1` lists the oldest first (the first active one is the default number). |
| `$select[]` | string | No | e.g. `$select[]=id&$select[]=label&$select[]=display_phone_number`. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/whatsapp-channels \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'organization_id=456' \
  --data-urlencode 'status=active' \
  --data-urlencode '$sort[id]=1'
```

#### Response

```json
{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 12,
      "organization_id": 456,
      "status": "active",
      "label": "Ventas",
      "display_phone_number": "+57 300 1234567",
      "verified_name": "Acme Store",
      "wa_ba_id": "104857600123456",
      "quality_rating": "GREEN"
    },
    {
      "id": 15,
      "organization_id": 456,
      "status": "active",
      "label": "Soporte",
      "display_phone_number": "+57 300 7654321",
      "verified_name": "Acme Store",
      "wa_ba_id": "104857600123456",
      "quality_rating": "GREEN"
    }
  ]
}
```

Each item is a full [WhatsApp channel object](#whatsapp-channels) (shortened here).

#### Notes

- Members restricted to some channel accounts only see the numbers they have access to.

<a id="whatsapp-channels--get"></a>

### Get a WhatsApp number

Source: https://www.achieveapex.com/docs/api-reference/whatsapp-channels/get

Retrieve one connected WhatsApp number by ID.

#### Endpoint

`GET /whatsapp-channels/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/whatsapp-channels/12 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 12,
  "organization_id": 456,
  "status": "active",
  "label": "Ventas",
  "display_phone_number": "+57 300 1234567",
  "verified_name": "Acme Store",
  "wa_ba_id": "104857600123456",
  "wa_phone_number_id": "109876543210987",
  "quality_rating": "GREEN",
  "whatsapp_business_manager_messaging_limit": "TIER_1K",
  "webhook_status": "subscribed",
  "created_at": "2026-01-05T12:00:00.000Z",
  "updated_at": "2026-02-10T08:00:00.000Z",
  "deleted_at": null
}
```

The response is the full [WhatsApp channel object](#whatsapp-channels) (shortened here).

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The ID does not exist, was removed, or belongs to an organization your API key cannot access. |

---

## WhatsApp templates

<a id="whatsapp-channel-message-templates"></a>

### WhatsApp templates overview

Source: https://www.achieveapex.com/docs/api-reference/whatsapp-channel-message-templates

WhatsApp message templates approved by Meta for your WhatsApp numbers. Templates are needed to write to a contact outside WhatsApp's 24-hour window; send one with [Send a WhatsApp template](#conversation-messages--send-whatsapp-template). Templates are created, edited and deleted in the AchieveApex app or in Meta's WhatsApp Manager; the API reads them.

#### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/whatsapp-channel-message-templates` | [List WhatsApp templates](#whatsapp-channel-message-templates--list) |
| `GET` | `/whatsapp-channel-message-templates/:id` | [Get a WhatsApp template](#whatsapp-channel-message-templates--get) |

#### The template object

```json
{
  "id": 812,
  "organization_id": 456,
  "whatsapp_channel_id": 12,
  "whatsapp_template_id": "1234567890123456",
  "name": "order_shipped",
  "language": "en_US",
  "category": "UTILITY",
  "status": "APPROVED",
  "components": [
    { "type": "BODY", "text": "Hi {{1}}, your order {{2}} arrives {{3}}." }
  ],
  "variables_matching": {
    "body_1": "contact_first_name",
    "body_2": "custom_body_2",
    "body_3": "custom_body_3"
  },
  "available_for_conversations": true,
  "available_for_campaigns": true,
  "meta_status_update": null,
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-01-11T09:00:00.000Z",
  "deleted_at": null
}
```

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | integer | Read-only. Unique ID. Send it as `template_id`. |
| `organization_id` | integer | Organization. |
| `whatsapp_channel_id` | integer | [WhatsApp number](#whatsapp-channels) the template was created or imported from. The template can be sent from any number of the same WhatsApp Business Account. |
| `whatsapp_template_id` | string \| null | Template ID in Meta. |
| `name` | string | Template name in Meta. |
| `language` | string | Language code, e.g. `en_US`, `es`. |
| `category` | string | `AUTHENTICATION`, `MARKETING` or `UTILITY`. |
| `status` | string | Review status: `APPROVED`, `PENDING` or `REJECTED`. Only approved templates are delivered. |
| `components` | array | Template components in Meta's format (`HEADER`, `BODY`, `FOOTER`, `BUTTONS`), with `{{n}}` placeholders. |
| `variables_matching` | object \| null | Maps each placeholder (`body_1`, `header_1`, ...) to the variable that fills it: a contact field such as `contact_first_name`, or a custom variable such as `custom_body_2` that you pass in `custom_variables` when sending. |
| `available_for_conversations` | boolean | Shown in the conversation composer. |
| `available_for_campaigns` | boolean | Available for WhatsApp campaigns. |
| `meta_status_update` | object \| null | Last status change notification received from Meta (for example the rejection reason). |
| `created_at` | string (date-time) | Read-only. |
| `updated_at` | string (date-time) | Read-only. |
| `deleted_at` | string (date-time) \| null | Read-only. Set when the template was deleted (in the app or in Meta). |

<a id="whatsapp-channel-message-templates--list"></a>

### List WhatsApp templates

Source: https://www.achieveapex.com/docs/api-reference/whatsapp-channel-message-templates/list

List the WhatsApp templates of your organization or of one WhatsApp number.

#### Endpoint

`GET /whatsapp-channel-message-templates`

#### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organization_id` | integer | No | Organization. Results are always limited to your API key's organization. |
| `whatsapp_channel_id` | integer | No | Templates of one WhatsApp number. Required with `$client[sync]` and `$client[waba_scope]`. |
| `status` | string | No | `APPROVED`, `PENDING` or `REJECTED`. |
| `category` | string | No | `AUTHENTICATION`, `MARKETING` or `UTILITY`. |
| `name` / `language` | string | No | Exact template name / language code. |
| `available_for_conversations` | boolean | No | `true` = templates offered in the conversation composer. |
| `$client[waba_scope]` | boolean | No | With `whatsapp_channel_id`: return every template of that number's WhatsApp Business Account once, including the ones created from another number of the same account. |
| `$client[sync]` | boolean | No | With `whatsapp_channel_id`: first fetch the templates from Meta, updating statuses, importing new ones and hiding deleted ones, then list. Slower; use it to refresh. |
| `$limit` / `$skip` | integer | No | Pagination. Default `10`, max `50`. |
| `$sort[name]` | `1` \| `-1` | No | Sort order. |

#### Request

```bash
curl -G https://integrations.achieveapex.com/whatsapp-channel-message-templates \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'whatsapp_channel_id=12' \
  --data-urlencode '$client[waba_scope]=true' \
  --data-urlencode 'status=APPROVED' \
  --data-urlencode '$limit=50'
```

#### Response

```json
{
  "total": 1,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "id": 812,
      "organization_id": 456,
      "whatsapp_channel_id": 12,
      "whatsapp_template_id": "1234567890123456",
      "name": "order_shipped",
      "language": "en_US",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": [{ "type": "BODY", "text": "Hi {{1}}, your order {{2}} arrives {{3}}." }],
      "variables_matching": { "body_1": "contact_first_name", "body_2": "custom_body_2", "body_3": "custom_body_3" },
      "available_for_conversations": true,
      "available_for_campaigns": true,
      "meta_status_update": null,
      "created_at": "2026-01-10T12:00:00.000Z",
      "updated_at": "2026-01-11T09:00:00.000Z",
      "deleted_at": null
    }
  ]
}
```

See [The template object](#whatsapp-channel-message-templates).

#### Errors

| Status | When |
|---|---|
| `400 Bad Request` | `$client[sync]` without a single `whatsapp_channel_id`, or Meta returned an error while syncing. |

<a id="whatsapp-channel-message-templates--get"></a>

### Get a WhatsApp template

Source: https://www.achieveapex.com/docs/api-reference/whatsapp-channel-message-templates/get

Retrieve one WhatsApp template by ID, for example to read its `variables_matching` before sending it.

#### Endpoint

`GET /whatsapp-channel-message-templates/:id`

#### Request

```bash
curl https://integrations.achieveapex.com/whatsapp-channel-message-templates/812 \
  -H "x-api-key: YOUR_API_KEY"
```

#### Response

```json
{
  "id": 812,
  "organization_id": 456,
  "whatsapp_channel_id": 12,
  "whatsapp_template_id": "1234567890123456",
  "name": "order_shipped",
  "language": "en_US",
  "category": "UTILITY",
  "status": "APPROVED",
  "components": [{ "type": "BODY", "text": "Hi {{1}}, your order {{2}} arrives {{3}}." }],
  "variables_matching": { "body_1": "contact_first_name", "body_2": "custom_body_2", "body_3": "custom_body_3" },
  "available_for_conversations": true,
  "available_for_campaigns": true,
  "meta_status_update": null,
  "created_at": "2026-01-10T12:00:00.000Z",
  "updated_at": "2026-01-11T09:00:00.000Z",
  "deleted_at": null
}
```

#### Errors

| Status | When |
|---|---|
| `404 Not Found` | The ID does not exist, was deleted, or belongs to an organization your API key cannot access. |
