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 (
$limitmax 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 headerX-Service-Method: <action>.
Contents
- Authentication
- Requests, filtering and pagination
- Errors and rate limits
- Use with AI and LLMs
- Activities: Overview · List activities · Get an activity · Create an activity · Update an activity · Delete an activity · Activities errors
- Activity types: Overview · List activity types · Get an activity type · Create an activity type · Update an activity type · Delete an activity type · Activity types errors
- AI Assistant Skills: Overview · List skills · Get a skill · Create a skill · Update a skill · Delete a skill
- AI Assistants: Overview · List AI assistants · Get an AI assistant · Create an AI assistant · Update an AI assistant · Delete an AI assistant · Configure a voice assistant · Get a history entry · List configuration history · List transcription languages · List voice LLM models · List voices · Restore a configuration version
- AI Models: Overview · List AI models · Get an AI model
- API Tools: Overview · List API tools · Get an API tool · Create an API tool · Update an API tool · Delete an API tool
- Automation executions: Overview · List executions · Get an execution · Run an automation
- Campaign Segments: Overview · List segments · Get a segment · Update a segment · Delete a segment · Export campaign segment contacts · Get segment fields · Preview the contacts of a segment
- Companies: Overview · List companies · Get a company · Create a company · Update a company · Delete a company · Companies errors · Search companies
- Contacts: Overview · List contacts · Get a contact · Create a contact · Update a contact · Delete a contact · Contacts errors · Search contacts
- Conversation files: Overview · List files · Get a file · Upload a file
- Conversation messages: Overview · List messages · Get a message · Edit a note · Delete a message · Send a message · Send a WhatsApp template
- Conversations: Overview · List conversations · Get a conversation · Create a conversation · Update a conversation · Delete a conversation · Get a bulk action · List bulk actions · Run a bulk action on conversations · Start a WhatsApp conversation
- Custom fields: Overview · List custom fields · Get a custom field · Create a custom field · Update a custom field · Delete a custom field
- Deal products: Overview · List deal products · Get a deal product · Add a product to a deal · Update a deal product · Remove a product from a deal · Deal products errors
- Deals: Overview · List deals · Get a deal · Create a deal · Update a deal · Delete a deal · Deals errors
- Export data: Overview · Export data
- Loyalty actions: Overview · Get wallet links · Load gift card balance · Register a purchase · Scan a code · Send the card link · Use a membership
- Loyalty members: Overview · List or look up loyalty members · Get a loyalty member · Enroll a loyalty member · Update a loyalty member · Delete a loyalty member
- Loyalty programs: Overview · List loyalty programs · Get a loyalty program · Create a loyalty program · Update a loyalty program · Delete a loyalty program
- Loyalty redemptions: Overview · List loyalty redemptions · Get a loyalty redemption · Redeem a reward · Use or cancel a redemption
- Loyalty reports: Overview
- Loyalty rewards: Overview · List loyalty rewards · Get a loyalty reward · Create a loyalty reward · Update a loyalty reward · Delete a loyalty reward
- Loyalty tiers: Overview · List loyalty tiers · Get a loyalty tier · Create a loyalty tier · Update a loyalty tier · Delete a loyalty tier
- Loyalty transactions: Overview · List loyalty transactions · Get a loyalty transaction · Adjust a balance
- MCP Tool Connections: Overview · Test an MCP connection
- Organization invitations: Overview · List invitations · Get an invitation · Create an invitation · Update an invitation · Cancel an invitation
- Organizations: Overview · List organizations · Get an organization · Update an organization · Organizations errors
- Pipeline stages: Overview · List pipeline stages · Get a pipeline stage · Create a pipeline stage · Update a pipeline stage · Delete a pipeline stage
- Pipelines: Overview · List pipelines · Get a pipeline · Create a pipeline · Update a pipeline · Delete a pipeline
- Predefined messages: Overview · List predefined messages · Get a predefined message · Create a predefined message · Update a predefined message · Delete a predefined message
- Product categories: Overview · List product categories · Get a product category · Create a product category · Update a product category · Delete a product category · Error Handling
- Product media: Overview · List product media · Get a product media item · Upload product media · Update product media · Delete product media · Error Handling
- Products: Overview · List products · Get a product · Create a product · Update a product · Delete a product · Error Handling
- Reservation available slots: Overview · Get available slots
- Reservation booking links: Overview · List reservation booking links · Get a reservation booking link · Create a reservation booking link · Update a reservation booking link · Delete a reservation booking link
- Reservation resource availability: Overview · List reservation resource availability · Get a reservation resource availability block · Create a reservation resource availability block · Update a reservation resource availability block · Delete a reservation resource availability block
- Reservation resource exceptions: Overview · List reservation resource exceptions · Get a reservation resource exception · Create a reservation resource exception · Update a reservation resource exception · Delete a reservation resource exception
- Reservation resources: Overview · List reservation resources · Get a reservation resource · Create a reservation resource · Update a reservation resource · Delete a reservation resource
- Reservation service resources: Overview · List reservation service resources · Get a reservation service resource · Create a reservation service resource · Update a reservation service resource · Delete a reservation service resource
- Reservation services: Overview · List reservation services · Get a reservation service · Create a reservation service · Update a reservation service · Delete a reservation service
- Reservations: Overview · List reservations · Get a reservation · Create a reservation · Update a reservation · Delete a reservation
- Support Tickets: Overview · List support tickets · Get a support ticket · Create a support ticket · Update a support ticket · Delete a support ticket · Support ticket errors
- Upload URLs: Overview · Create an upload URL
- WhatsApp numbers: Overview · List WhatsApp numbers · Get a WhatsApp number
- WhatsApp templates: Overview · List WhatsApp templates · Get a WhatsApp template
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.
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
- In AchieveApex, go to Settings → Developers → API Keys.
- Create a key and copy it. Each key belongs to one organization and to the user who created it.
- 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
curl -G https://integrations.achieveapex.com/contacts \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode '$limit=5'
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) returns403 Forbidden. - Most resources require
organization_idin the body ofPOSTrequests: use your organization's ID (GET /organizationsreturns 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_idon 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. |
Next steps
- Requests, filtering and pagination: how to list, filter, sort and page through any resource.
- Errors and rate limits
- Use with AI and LLMs: one-file download, OpenAPI spec and prompts.
- Start with a resource, for example Contacts.
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:
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:
{
"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.
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
{
"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:
{
"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,503and network errors with exponential backoff. GET,PATCHandDELETEare safe to retry.POSTcreates a new record each time: before retrying aPOSTthat may have succeeded, list with a filter (for example byemail) to check it does not already exist.- Do not retry
400,401,403or404without changing the request.
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 |
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 |
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 |
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 |
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
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 |
GET |
/activities/:id |
Get an activity |
POST |
/activities |
Create an activity |
PATCH |
/activities/:id |
Update an activity |
DELETE |
/activities/:id |
Delete an activity |
Reads are limited to your API key's organization. Pass organization_id as a filter to work with one organization.
The activity object
{
"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. |
contact_id |
integer | null | Linked contact. |
company_id |
integer | null | Linked company. |
activity_type |
string | Type of activity. Default call. The built-in types are call, meeting, task, deadline, email and lunch; see also 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_typeand the activity is notdone. Sync errors do not fail the request; they setsync_statustofailed. - When
assigned_to_user_id,start_dateandstart_timeare 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
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
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
{
"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; it is shortened here.
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
curl -G https://integrations.achieveapex.com/activities/321 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the activity object.
{
"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 }
}
Create an activity
Source: https://www.achieveapex.com/docs/api-reference/activities/create
Creates an activity. See side effects 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 are rejected. created_by_user_id is set to the API key's user.
Request
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 with linked records embedded.
{
"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.
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. Fields not in the object are rejected.
Request
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 with linked records embedded.
{
"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.
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
curl -X DELETE https://integrations.achieveapex.com/activities/321 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted activity object with deleted_at set.
{
"id": 321,
"organization_id": 456,
"subject": "Follow-up call",
"deleted_at": "2026-04-16T08:00:00.000Z"
}
Activities errors
Source: https://www.achieveapex.com/docs/api-reference/activities/errors
Errors use the standard Feathers error format.
{
"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
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, on top of the built-in ones.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/activity-types |
List activity types |
GET |
/activity-types/:id |
Get an activity type |
POST |
/activity-types |
Create an activity type |
PATCH |
/activity-types/:id |
Update an activity type |
DELETE |
/activity-types/:id |
Delete an activity type |
Reads are limited to your API key's organization. Pass organization_id as a filter to work with one organization.
The activity type object
{
"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
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
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
{
"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
}
]
}
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
curl -G https://integrations.achieveapex.com/activity-types/5 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the activity type object.
{
"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
}
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
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
{
"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
}
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
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.
{
"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
}
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
curl -X DELETE https://integrations.achieveapex.com/activity-types/5 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted activity type object with deleted_at set.
{
"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"
}
Activity types errors
Source: https://www.achieveapex.com/docs/api-reference/activity-types/errors
Errors use the standard Feathers error format.
{
"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
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 |
GET |
/ai-assistant-skills/:id |
Get a skill |
POST |
/ai-assistant-skills |
Create a skill |
PATCH |
/ai-assistant-skills/:id |
Update a skill |
DELETE |
/ai-assistant-skills/:id |
Delete a skill |
Reads are limited to your API key's organization.
The skill object
{
"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 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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/ai-assistant-skills/701 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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
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
{
"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. |
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
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.
{
"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
}
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
curl -X DELETE https://integrations.achieveapex.com/ai-assistant-skills/9001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
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 |
GET |
/ai-assistants/:id |
Get an AI assistant |
POST |
/ai-assistants |
Create an AI assistant |
PATCH |
/ai-assistants/:id |
Update an AI assistant |
PATCH |
/ai-assistants/:id |
Configure a voice assistant |
DELETE |
/ai-assistants/:id |
Delete an AI assistant |
GET |
/ai-assistants-change-history |
List configuration history |
GET |
/ai-assistants-change-history/:id |
Get a history entry |
POST |
/ai-assistants-restore-from-changes-history |
Restore a configuration version |
GET |
/telnyx-ai-models |
List voice LLM models |
GET |
/telnyx-ai-voices |
List voices |
GET |
/telnyx-ai-transcription-languages |
List 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
{
"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. 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. |
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. |
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 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. |
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. |
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
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 can be used as an exact-match filter. Results are always limited to your API key's organization and exclude deleted assistants.
Request
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:
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
{
"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; the example is shortened.
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
curl https://integrations.achieveapex.com/ai-assistants/123 \
-H "x-api-key: YOUR_API_KEY"
Refresh a voice assistant from the voice provider:
curl -G https://integrations.achieveapex.com/ai-assistants/501 \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode '$syncFromTelnyx=true'
Response
{
"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 (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. |
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. |
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. |
Every other writable field of the AI assistant object can also be sent on create; the same shapes as in Update an AI assistant apply. Unknown top-level fields are rejected.
What the server does on create:
- Generates
version_id. voiceassistants getvoice_enabled: trueand, 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-chatandhelpdeskassistants get a defaultinternal_toolsset (it replaces anyinternal_toolsyou send).conversation,support-ticketandai-chatassistants getadvanced_options.conversation_summary_config.enabled: trueunless you set it.- Media send flags (
can_send_images, ...) are turned on wheninstructionsreference media from the assistant media library. created_by_user_idis not filled in for API key requests, and no change history entry is recorded.
Request
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:
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 (shortened):
{
"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. |
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. 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. |
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. |
mcp_tools |
array | null | Connected MCP servers. |
telnyx_ai_assistant_config |
object | null | Voice configuration. See Configure a voice assistant. |
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.
Request
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, including the read-only ai_safeguards_system object (shortened):
{
"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.
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.
{
"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.
{
"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.
{
"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
{
"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
{
"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
{
"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 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 |
{ "ai_safeguards": { "max_responses_per_minute": 10, "anomaly_detection_enabled": true } }
Schedule
{
"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
{
"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, then attach it:
{
"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, then store it:
{
"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). |
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
curl -X DELETE https://integrations.achieveapex.com/ai-assistants/123 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted AI assistant object, with deleted_at set.
{
"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, remove id, version_id, created_by_user_id, created_at, updated_at, deleted_at and ai_safeguards_system, change name, and create a new one.
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, voices and transcription languages.
Request
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 (shortened):
{
"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. |
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 (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. |
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
{ "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
{
"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:
<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).
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).
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 for the fields.
Endpoint
GET /ai-assistants-change-history/:id
Request
curl https://integrations.achieveapex.com/ai-assistants-change-history/9001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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. |
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 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
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):
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
{
"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
}
}
]
}
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
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
{
"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.
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
curl https://integrations.achieveapex.com/telnyx-ai-models \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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
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:
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.
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
{
"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. |
Restore a configuration version
Source: https://www.achieveapex.com/docs/api-reference/ai-assistants/restore
Restore an assistant from a history entry, 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. |
instructionsrestoresinstructionsandinstructions_language.allrestoresname,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_targetsandadditional_json_keys. Other fields (tools, schedule, follow-ups, voice settings, ...) are left as they are.
Request
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
{
"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
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.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/ai-models |
List AI models |
GET |
/ai-models/:id |
Get an AI model |
The catalog is the same for every organization. Creating, changing or deleting models is reserved to AchieveApex administrators.
The AI model object
{
"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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/ai-models/12 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 (shortened above).
Errors
| Status | When |
|---|---|
404 |
The model does not exist or is deleted. |
API Tools
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 |
GET |
/api-tools/:id |
Get an API tool |
POST |
/api-tools |
Create an API tool |
PATCH |
/api-tools/:id |
Update an API tool |
DELETE |
/api-tools/:id |
Delete an API tool |
Reads are limited to your API key's organization.
The API tool object
{
"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
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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/api-tools/88 \
-H "x-api-key: YOUR_API_KEY"
Response
The API tool object.
{
"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. |
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. |
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
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:
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, 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. |
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
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.
{
"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"
}
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 so the association list stays clean.
Request
curl -X DELETE https://integrations.achieveapex.com/api-tools/77 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted API tool object, with deleted_at set.
{
"id": 77,
"organization_id": 27,
"name": "shipment_lookup",
"deleted_at": "2026-04-25T13:00:00.000Z"
}
Automation executions
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 |
GET |
/automations-executions |
List executions |
GET |
/automations-executions/:id |
Get an execution |
The execution object
{
"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 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. |
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
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
{
"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.
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 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
curl https://integrations.achieveapex.com/automations-executions/90210 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 (shortened here).
Errors
| Status | When |
|---|---|
404 Not Found |
The ID does not exist or belongs to an organization your API key cannot access. |
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):
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:
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:
{
"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 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
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 |
GET |
/campaign-segments/:id |
Get a segment |
PATCH |
/campaign-segments/:id |
Update a segment |
DELETE |
/campaign-segments/:id |
Delete a segment |
POST |
/contacts-segments-schema-builder |
Get the fields you can filter on |
POST |
/contacts-segments-run-query |
Preview the contacts of a segment |
Reads are limited to your API key's organization. Creating and splitting segments is currently only available in the AchieveApex app.
The segment object
{
"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
{
"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. 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
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
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
{
"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.
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
curl https://integrations.achieveapex.com/campaign-segments/501 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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. | |
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:
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:
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 (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.
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. |
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
curl -X DELETE https://integrations.achieveapex.com/campaign-segments/501 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted segment object, with deleted_at set.
{
"id": 501,
"organization_id": 456,
"name": "VIP customers",
"channel": "whatsapp",
"deleted_at": "2026-02-10T09:00:00.000Z"
}
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
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
{
"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
querymust be non-empty for the preview export path in the app (the UI blocks empty queries).
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
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
{
"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. |
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
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
{
"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
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 |
GET |
/companies/:id |
Get a company |
POST |
/companies |
Create a company |
PATCH |
/companies/:id |
Update a company |
DELETE |
/companies/:id |
Delete a company |
POST |
/companies + X-Service-Method: search |
Search companies |
Reads are limited to your API key's organization. Pass organization_id as a filter to work with one organization.
The company object
{
"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, 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
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
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
{
"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; it is shortened here.
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
curl -G https://integrations.achieveapex.com/companies/101 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the company object.
{
"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
}
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 are rejected. created_by_user_id is always set to the API key's user.
Request
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
{
"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
}
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. custom_fields_by_key is merged with the existing values; send a key with null to clear it.
Request
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.
{
"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
}
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
curl -X DELETE https://integrations.achieveapex.com/companies/101 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted company object with deleted_at set.
{
"id": 101,
"name": "Acme Corporation",
"organization_id": 456,
"updated_at": "2026-01-04T00:00:00.000Z",
"deleted_at": "2026-01-04T00:00:00.000Z"
}
Companies errors
Source: https://www.achieveapex.com/docs/api-reference/companies/errors
Errors use the standard Feathers error format.
{
"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. |
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
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
{
"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; 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
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 |
GET |
/contacts/:id |
Get a contact |
POST |
/contacts |
Create a contact |
PATCH |
/contacts/:id |
Update a contact |
DELETE |
/contacts/:id |
Delete a contact |
POST |
/contacts + X-Service-Method: search |
Search contacts |
Reads are limited to your API key's organization. Pass organization_id as a filter to work with one organization.
The contact object
{
"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 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, 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
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
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:
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
{
"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; it is shortened here.
Notes
- With
searchTerm, results are sorted byfirst_nameunless you pass$sortonfirst_name,last_name,email,created_atorupdated_at. Terms shorter than 3 characters (or a lone+or digit) return an empty page. searchIn=allalso matches custom field values when the term has 4 or more characters.
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
curl -G https://integrations.achieveapex.com/contacts/123 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the contact object.
{
"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. |
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 is accepted. created_by_user_id is always set to the API key's user.
Request
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
{
"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. |
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. Unknown fields are rejected.
custom_fields_by_keyis merged with the existing values: only the keys you send change. Send a key withnullto clear it.custom_fields_by_nameandcustom_fields_meta_dataare rebuilt automatically.- Changing any
*_blacklistfield (Do Not Disturb) setsdnd_updated_atto now anddnd_sourcetomanualunless you send them. phoneis normalized the same way as on create.
Request
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.
{
"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.
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
curl -X DELETE https://integrations.achieveapex.com/contacts/123 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted contact object with deleted_at set.
{
"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"
}
Contacts errors
Source: https://www.achieveapex.com/docs/api-reference/contacts/errors
Errors use the standard Feathers error format.
{
"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. |
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, 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
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
{
"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; 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
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.
Endpoints
| Method | Path | Description |
|---|---|---|
POST |
/conversation-files |
Upload a file |
GET |
/conversation-files |
List files |
GET |
/conversation-files/:id |
Get a file |
The conversation file object
{
"_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
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
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
{
"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.
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
curl https://integrations.achieveapex.com/conversation-files/65e0a1b2c3d4e5f6a7b8c9d0 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"_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. |
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
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"
}'
{
"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. The URL is valid for 1 hour.
Step 2: Upload the bytes
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
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 with its _id:
{
"_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 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
Conversation messages overview
Source: https://www.achieveapex.com/docs/api-reference/conversation-messages
Messages of a conversation. 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 |
| Get one message | Get a message |
| Send text, media, location or an internal note | Send a message |
| Send a WhatsApp template | Send a WhatsApp template |
| Edit an internal note | Edit a note |
| Delete a message | Delete a message |
Attachments are uploaded first with Conversation files.
The message object
A WhatsApp message (other channels share the same core fields):
{
"_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 | 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 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 | The contact deleted the message in WhatsApp. | |
edited |
boolean | null | The message was edited (by the contact in WhatsApp, or an edited internal note). | |
message_text_original |
string | null | Text before the edit. | |
order_data |
object | null | WhatsApp catalog order sent by the contact. | |
interactive_data |
object | null | Interactive reply (list or button) sent by the contact. | |
interactive_type |
string | null | Type of the interactive reply. | |
button_data |
object | null | 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 | 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 | 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 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.
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-instagramGET /conversation-messages-messengerGET /conversation-messages-webchatGET /conversation-messages-smsGET /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 can be used as a filter.
Request
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
{
"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.
Notes
- Deleted messages are not returned.
- Members restricted to some channel accounts get
403 Forbiddenfor conversations of accounts they cannot see.
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/:idGET /conversation-messages-messenger/:idGET /conversation-messages-webchat/:idGET /conversation-messages-sms/:idGET /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
curl https://integrations.achieveapex.com/conversation-messages-whatsapp/65d1c0a1b2c3d4e5f6a7b8c9 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"_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.
Errors
| Status | When |
|---|---|
404 Not Found |
The message does not exist or was deleted. |
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/:idPATCH /conversation-messages-messenger/:idPATCH /conversation-messages-webchat/:idPATCH /conversation-messages-playground/:id
Body
| Name | Type | Required | Description |
|---|---|---|---|
message_text |
string | Yes | New note text. 1 to 20,000 characters. |
Request
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. On every channel except playground, edited becomes true and message_text_original keeps the first text.
{
"_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. |
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/:idDELETE /conversation-messages-messenger/:idDELETE /conversation-messages-webchat/:idDELETE /conversation-messages-sms/:idDELETE /conversation-messages-playground/:id
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | integer | Yes | Message _id (integer id for playground). |
Request
curl -X DELETE https://integrations.achieveapex.com/conversation-messages-whatsapp/65d1c0a1b2c3d4e5f6a7b8c9 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted message with deleted_at set. If the message was pinned on the conversation it is unpinned.
{
"_id": "65d1c0a1b2c3d4e5f6a7b8c9",
"conversation_id": 5001,
"message_type": "text",
"deleted_at": "2026-02-10T18:10:00.000Z"
}
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) |
playground |
POST /conversation-messages-playground (see below) |
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). |
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. |
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 |
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 | no | no | no |
Request
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):
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:
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:
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:
{
"_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. 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. |
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). 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.
| 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). |
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. |
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).
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. 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
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, with message_type: "template" and the rendered text in message_text.
{
"_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
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.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/conversations |
List conversations |
GET |
/conversations/:id |
Get a conversation |
POST |
/conversations |
Create a conversation |
PATCH |
/conversations/:id |
Update a conversation |
DELETE |
/conversations/:id |
Delete a conversation |
POST |
/conversation-initiate-whatsapp |
Start a WhatsApp conversation |
POST |
/conversations-bulk-actions |
Run a bulk action |
GET |
/conversations-bulk-actions |
List bulk actions |
GET |
/conversations-bulk-actions/:id |
Get a bulk action |
The conversation object
{
"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 holds its messages. |
contact_id |
integer | Contact on the other side. Required on create. |
whatsapp_channel_id |
integer | null | WhatsApp conversations: the WhatsApp number 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 answering the thread. null = no AI. Must belong to the same organization. |
pipeline_id |
integer | null | Conversation pipeline (type conversation). |
pipeline_stage_id |
integer | null | Stage 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. |
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). |
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: list, send and delete messages
- Conversation files: attachments
- Predefined messages: canned replies
- WhatsApp numbers and WhatsApp templates
- Automation executions: run an automation on a conversation
- Pipelines and Pipeline stages (type
conversation)
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 can be used as a filter with the standard operators. 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). |
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
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:
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
{
"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 (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.
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
curl https://integrations.achieveapex.com/conversations/5001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 (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. |
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 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 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 is accepted. meta_contact_tags is always copied from the contact.
Request
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) and the assistant replies in the same thread.
Response
{
"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_phoneandour_phone_numberalready 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. |
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. 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). |
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
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:
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:
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.
{
"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_idnotifies 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. |
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
curl -X DELETE https://integrations.achieveapex.com/conversations/5001 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted conversation object, with deleted_at set.
{
"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. |
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
curl https://integrations.achieveapex.com/conversations-bulk-actions/310 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. Only owners and admins of the organization can read bulk actions.
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
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
{
"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. |
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
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:
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. With a filter, conversation_ids contains the IDs it resolved to.
{
"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. |
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. 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
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. If the contact already has a conversation on that number it is returned instead of creating a new one.
{
"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_idis filled fromphone_country_code+phone. - Then send a WhatsApp template (required to open a chat outside the 24-hour window) or a regular message.
- 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
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 |
GET |
/custom-fields/:id |
Get a custom field |
POST |
/custom-fields |
Create a custom field |
PATCH |
/custom-fields/:id |
Update a custom field |
DELETE |
/custom-fields/:id |
Delete a custom field |
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
{
"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:
{
"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
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
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
{
"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
}
]
}
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
curl -G https://integrations.achieveapex.com/custom-fields/12 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the custom field object.
{
"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
}
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. |
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
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
{
"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. |
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: name, fieldType, isRequired, options, system_currency_id, custom_field_category_id, position. A new name must still be unique for the entity type.
Request
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/custom-fields/12 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted custom field object with deleted_at set.
{
"id": 12,
"organization_id": 456,
"entity_type": "contact",
"name": "Membership level",
"key": "membership_level",
"deleted_at": "2026-01-06T00:00:00.000Z"
}
Deal products
Deal products overview
Source: https://www.achieveapex.com/docs/api-reference/deal-products
A deal product is a line item on a deal: 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 |
GET |
/deal-products/:id |
Get a deal product |
POST |
/deal-products |
Add a product to a deal |
PATCH |
/deal-products/:id |
Update a deal product |
DELETE |
/deal-products/:id |
Remove a product from a deal |
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
{
"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 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
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
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
{
"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
}
]
}
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
curl -G https://integrations.achieveapex.com/deal-products/501 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deal product object.
{
"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
}
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
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
{
"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
}
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. Fields not in the object are rejected.
Request
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.
{
"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
}
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
curl -X DELETE https://integrations.achieveapex.com/deal-products/501 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted deal product object with deleted_at set.
{
"id": 501,
"deal_id": 55,
"name": "Annual license",
"deleted_at": "2026-04-03T08:00:00.000Z"
}
Deal products errors
Source: https://www.achieveapex.com/docs/api-reference/deal-products/errors
Errors use the standard Feathers error format.
{
"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
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. 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 |
GET |
/deals/:id |
Get a deal |
POST |
/deals |
Create a deal |
PATCH |
/deals/:id |
Update a deal |
DELETE |
/deals/:id |
Delete a deal |
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
{
"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 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 (type: deal). Required on create. |
pipeline_stage_id |
integer | Current stage of the pipeline. Required on create. |
contact_id |
integer | null | Contact of the deal. Required on create. |
company_id |
integer | null | Linked company. |
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, 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
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). |
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
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
{
"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; it is shortened here.
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). |
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
curl -G https://integrations.achieveapex.com/deals/55 \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode 'fastJoinForDealsList=true'
Response
Returns the deal object.
{
"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. |
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 are rejected. created_by_user_id is set to the API key's user.
Request
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
{
"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. |
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. Fields not in the object are rejected.
status: "won"setswon_date;status: "lost"setslost_date;status: "open"clears both dates and the lost reason.deal_lost_reason_idfillsdeal_lost_reasonwith the reason text.- Changing
pipeline_stage_idcloses the current stage in the stage history and opens the new one. - Changing
currency_idrecalculatesexchange_rateunless you send it. custom_fields_by_keyis merged with existing values; send a key withnullto clear it.
Request
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 with related data embedded (see embedded data).
{
"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.
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
curl -X DELETE https://integrations.achieveapex.com/deals/55 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted deal object with deleted_at set.
{
"id": 55,
"name": "Annual plan",
"organization_id": 456,
"deleted_at": "2026-05-03T08:00:00.000Z"
}
Deals errors
Source: https://www.achieveapex.com/docs/api-reference/deals/errors
Errors use the standard Feathers error format.
{
"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
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 |
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_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
{
"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
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. |
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
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
{
"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
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 |
POST |
/loyalty-actions |
register_purchase: register a purchase or visit |
POST |
/loyalty-actions |
use_membership: check in a membership |
POST |
/loyalty-actions |
load_balance: top up a gift card |
POST |
/loyalty-actions |
wallet_links: card page and wallet links |
POST |
/loyalty-actions |
send_card: email the card link |
POST |
/loyalty-actions |
refresh_pass and recompute_tiers (see Actions) |
organization_id is required in every body and must be the API key's organization. There is no list, get, update or delete.
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 |
code |
Finds a card (card code or referral code) or a reward code |
register_purchase |
member_id, amount, note, reference |
Registers a purchase or visit and awards points, stamps or cashback |
use_membership |
member_id, note |
Uses one check-in of a membership |
load_balance |
member_id, amount, description |
Tops up a gift card |
wallet_links |
member_id |
Returns the card page and the Apple Wallet / Google Wallet links |
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). 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 (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).
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
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
{
"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 |
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
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
{
"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 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.
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 |
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
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
{
"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, 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 or load_balance) |
This program is not active |
The program is draft, paused or archived |
Amount cannot be negative |
amount is below zero |
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
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
{
"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 (shortened above). rewards lists the active rewards of the card's program, cheapest first. To redeem one, see Redeem a Reward.
A reward code
{
"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.
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".
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
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
{
"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 |
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
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
{
"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 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
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 |
GET |
/loyalty-members/:id |
Get a loyalty member |
POST |
/loyalty-members |
Enroll a loyalty member |
PATCH |
/loyalty-members/:id |
Update a loyalty member |
DELETE |
/loyalty-members/:id |
Delete a loyalty member |
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
{
"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 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 or the scan action. |
balance |
number | Read-only. Current balance: points, stamps, money (cashback / gift card) or uses left (membership). Changed only through actions, redemptions and adjustments. |
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, 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. For the balance history, see Loyalty Transactions.
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)
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:
- The exact card code (
member_code) or referral code (case and spaces are ignored). - An email address (exact match on the contact email) when the value contains
@. - 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
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
{
"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 (the example above is shortened). When nothing matches, data is an empty list.
When both lookup and search are sent, only lookup is used.
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
curl https://integrations.achieveapex.com/loyalty-members/3001 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the full Loyalty Member object with contact, tier, program and card_url.
{
"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"
}
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
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
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
{
"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 plus already_enrolled. Send card_url to the customer (or use the 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 validreferral_codeis 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).
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 or a manual adjustment.
Endpoint
PATCH /loyalty-members/:id
Request
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
{
"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 (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.
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 with "status": "blocked" instead.
Endpoint
DELETE /loyalty-members/:id
Request
curl -X DELETE https://integrations.achieveapex.com/loyalty-members/3001 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted loyalty member with deleted_at set (and contact, tier, program, card_url).
{
"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 previousstatus) and its Apple Wallet and Google Wallet passes are refreshed so they stop working. - The program
member_countgoes down by one. - The card's transactions are kept and still listed.
Loyalty programs
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 |
GET |
/loyalty-programs/:id |
Get a loyalty program |
POST |
/loyalty-programs |
Create a loyalty program |
PATCH |
/loyalty-programs/:id |
Update a loyalty program |
DELETE |
/loyalty-programs/:id |
Delete a loyalty program |
All requests use your API key in the x-api-key header (see 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 |
| Enroll a customer (idempotent) | POST /loyalty-members |
| Find a card by phone, email or card code | GET /loyalty-members?lookup= |
| Scan a card or reward QR code | POST /loyalty-actions scan |
| Register a purchase or visit | POST /loyalty-actions register_purchase |
| Redeem a reward or balance | POST /loyalty-redemptions |
| Mark a reward code used or cancel it | PATCH /loyalty-redemptions/:id |
| Manual balance adjustment | POST /loyalty-transactions |
| Balance history | GET /loyalty-transactions |
| Card page and Apple / Google Wallet links | POST /loyalty-actions wallet_links |
| KPIs | GET /loyalty-reports |
The loyalty program object
{
"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). 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 (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".
{
"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) |
500 Internal Server Error |
Server error |
Related
Loyalty Members, Loyalty Actions, Loyalty Transactions, Loyalty Redemptions, Loyalty Rewards, Loyalty Tiers and Loyalty Reports.
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
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
{
"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 (the example above is shortened).
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
curl https://integrations.achieveapex.com/loyalty-programs/12 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the full Loyalty Program object, including the calculated enrollment_url and wallet_availability.
{
"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 }
}
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. |
Request
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 with enrollment_url and wallet_availability.
{
"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. |
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 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
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 (same shape as Get a loyalty program).
Side effects
- Changing
name,card_design,terms,locations,status,stamps_requiredorcurrency_coderefreshes every installed Apple Wallet and Google Wallet card of the program in the background. - Changing
tiers_enabledortier_basisrecalculates every member's tier in the background. archivedprograms 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 also apply, checked against the program after the change.
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 with "status": "archived" instead.
Endpoint
DELETE /loyalty-programs/:id
Request
curl -X DELETE https://integrations.achieveapex.com/loyalty-programs/13 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted loyalty program with deleted_at set.
{
"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
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; 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 |
GET |
/loyalty-redemptions/:id |
Get a loyalty redemption |
POST |
/loyalty-redemptions |
Redeem a reward |
PATCH |
/loyalty-redemptions/:id |
Use or cancel a redemption |
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
{
"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 that spent the balance. |
contact_id |
integer | null | Read-only. Contact of the card. |
reward_id |
integer | null | Read-only. Redeemed reward. null for balance (amount) redemptions. |
transaction_id |
integer | null | Read-only. The transaction 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.
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
curl -G https://integrations.achieveapex.com/loyalty-redemptions \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode 'organization_id=456' \
--data-urlencode 'search=XH4K9PRT'
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
{
"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 action. To retrieve one redemption, see Get a loyalty redemption.
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
curl https://integrations.achieveapex.com/loyalty-redemptions/801 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 or the scan action.
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
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
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
{
"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. Without mark_used, status is issued: give the code to the customer and mark it used 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) |
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.
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
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"
}'
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
{
"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
usedonly works on anissuedcode 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.cancelledis meant forissuedcodes: it gives thecostback to the card balance (areversaltransaction) 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
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
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
{
"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
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. Rewards can be managed in the Loyalty app or through this API.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/loyalty-rewards |
List loyalty rewards |
GET |
/loyalty-rewards/:id |
Get a loyalty reward |
POST |
/loyalty-rewards |
Create a loyalty reward |
PATCH |
/loyalty-rewards/:id |
Update a loyalty reward |
DELETE |
/loyalty-rewards/:id |
Delete a loyalty reward |
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
{
"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 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, if any. |
min_tier_id |
integer | null | Minimum tier 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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/loyalty-rewards/21 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
}
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. |
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
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
{
"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. |
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 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
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.
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. |
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
curl -X DELETE https://integrations.achieveapex.com/loyalty-rewards/21 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted reward with deleted_at set.
{
"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
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 |
GET |
/loyalty-tiers/:id |
Get a loyalty tier |
POST |
/loyalty-tiers |
Create a loyalty tier |
PATCH |
/loyalty-tiers/:id |
Update a loyalty tier |
DELETE |
/loyalty-tiers/:id |
Delete a loyalty tier |
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
{
"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 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
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
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
{
"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.
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
curl https://integrations.achieveapex.com/loyalty-tiers/4 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
}
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. |
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
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
{
"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). |
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
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. 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). |
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
curl -X DELETE https://integrations.achieveapex.com/loyalty-tiers/4 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted tier with deleted_at set.
{
"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
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 |
GET |
/loyalty-transactions/:id |
Get a loyalty transaction |
POST |
/loyalty-transactions |
Adjust a balance |
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
{
"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 whose balance moved. |
contact_id |
integer | null | Read-only. Contact of the card. |
type |
string | Read-only. Kind of movement (see 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. 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) |
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
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
{
"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.
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
curl https://integrations.achieveapex.com/loyalty-transactions/5121 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
}
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 instead.
Endpoint
POST /loyalty-transactions
Request
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
{
"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.
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_daysexpires 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
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 |
PATCH |
/ai-assistants/:id |
Save connections on an assistant |
The MCP connection object
{
"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
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
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
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.
{
"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:
{
"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.
Organization invitations
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 |
GET |
/organizations-users-invites/:id |
Get an invitation |
POST |
/organizations-users-invites |
Create an invitation |
PATCH |
/organizations-users-invites/:id |
Update an invitation |
DELETE |
/organizations-users-invites/:id |
Cancel an invitation |
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
{
"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
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
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
{
"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
}
]
}
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
curl -G https://integrations.achieveapex.com/organizations-users-invites/77 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the invitation object.
{
"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
}
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
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
{
"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). |
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
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/organizations-users-invites/77 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the cancelled invitation object with deleted_at set.
{
"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
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 |
GET |
/organizations/:id |
Get an organization |
PATCH |
/organizations/:id |
Update an organization |
You can only read and update the organizations the API key's user belongs to.
The organization object
{
"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. |
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
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
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
{
"total": 1,
"limit": 10,
"skip": 0,
"data": [
{
"id": 456,
"name": "My Business",
"timezone": "America/Bogota"
}
]
}
Without $select, each item is a full organization object.
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
curl -G https://integrations.achieveapex.com/organizations/456 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the organization object 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.
{
"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" }.
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_minimummust be at least the platform minimum threshold and not below the organization's recent average daily usage.wallet_auto_recharge_amountmust be greater thanwallet_auto_recharge_minimumand large enough to cover several days of average usage.
The error message states the exact minimum allowed for your organization.
Request
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.
{
"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. |
Organizations errors
Source: https://www.achieveapex.com/docs/api-reference/organizations/errors
Errors use the standard Feathers error format.
{
"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
Pipeline stages overview
Source: https://www.achieveapex.com/docs/api-reference/pipeline-stages
A stage is one column of a pipeline, 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 |
GET |
/pipeline-stages/:id |
Get a pipeline stage |
POST |
/pipeline-stages |
Create a pipeline stage |
PATCH |
/pipeline-stages/:id |
Update a pipeline stage |
DELETE |
/pipeline-stages/:id |
Delete a pipeline stage |
Reads are limited to your API key's organization and to stages of pipelines the key's user can see (see pipeline visibility). Creating, updating and deleting stages is not allowed when the key's user has the member role in the organization.
The pipeline stage object
{
"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
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
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
{
"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.
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
curl -G https://integrations.achieveapex.com/pipeline-stages/101 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the pipeline stage object.
{
"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. |
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
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
{
"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. |
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
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.
{
"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. |
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
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 with deleted_at set.
{
"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
Pipelines overview
Source: https://www.achieveapex.com/docs/api-reference/pipelines
A pipeline is an ordered set of 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 |
GET |
/pipelines/:id |
Get a pipeline |
POST |
/pipelines |
Create a pipeline |
PATCH |
/pipelines/:id |
Update a pipeline |
DELETE |
/pipelines/:id |
Delete a pipeline |
Reads are limited to your API key's organization. Pass organization_id and type as filters.
Visibility and permissions
- A
publicpipeline is visible to every member of the organization. Aprivatepipeline 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
memberrole in the organization (403 Forbidden).
The pipeline object
{
"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). 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 |
|
messenger |
Messenger |
webchat |
Webchat |
sms |
SMS |
An empty or missing list means every channel, including channels connected later.
- Listing conversations with
pipeline_idorincoming_pipeline_idonly returns conversations of the pipeline's channels. - A conversation cannot be moved into a pipeline that does not accept its channel: patching a conversation returns
400withdata.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).
Related
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
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
{
"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 with pipeline_id.
Get a pipeline
Source: https://www.achieveapex.com/docs/api-reference/pipelines/get
Returns one pipeline by ID.
Endpoint
GET /pipelines/:id
Request
curl -G https://integrations.achieveapex.com/pipelines/10 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the pipeline object.
{
"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. |
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.
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); WhatsApp numbers must belong to the organization. |
created_by_user_id is set to the API key's user.
Request
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
{
"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. |
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
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). Send [] to accept every channel again.
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). |
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/pipelines/10 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted pipeline object with deleted_at set.
{
"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. |
{
"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
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 |
GET |
/conversation-predefined-messages/:id |
Get a predefined message |
POST |
/conversation-predefined-messages |
Create a predefined message |
PATCH |
/conversation-predefined-messages/:id |
Update a predefined message |
DELETE |
/conversation-predefined-messages/:id |
Delete a predefined message |
The predefined message object
{
"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 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.
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/conversation-predefined-messages/42 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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 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
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:
{
"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. |
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).
Request
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/conversation-predefined-messages/42 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted predefined message with deleted_at set.
{
"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
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 |
GET |
/products-categories/:id |
Get a product category |
POST |
/products-categories |
Create a product category |
PATCH |
/products-categories/:id |
Update a product category |
DELETE |
/products-categories/:id |
Delete a product category |
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
{
"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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/products-categories/5 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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.
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
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
{
"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
}
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
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
{
"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
}
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
curl -X DELETE https://integrations.achieveapex.com/products-categories/8 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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.
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
{
"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
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 |
GET |
/products-media/:id |
Get a product media item |
POST |
/products-media |
Upload product media |
PATCH |
/products-media/:id |
Update product media |
DELETE |
/products-media/:id |
Delete product media |
The API key is scoped to one organization: reads are filtered to it automatically.
The product media object
{
"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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/products-media/456 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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
}
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
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. |
{
"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
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
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
{
"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: …). |
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 are also accepted, but changing file_path, s3_key or s3_path does not move the stored file. organization_id cannot be changed.
Request
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
{
"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
}
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
curl -X DELETE https://integrations.achieveapex.com/products-media/459 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 deletes all its media.
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
{
"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
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 |
GET |
/products/:id |
Get a product |
POST |
/products |
Create a product |
PATCH |
/products/:id |
Update a product |
DELETE |
/products/:id |
Delete a product |
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
{
"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 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
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
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:
curl -G https://integrations.achieveapex.com/products \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode 'searchTerm=premium' \
--data-urlencode '$limit=10'
Response
{
"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.
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. |
Request
curl https://integrations.achieveapex.com/products/123 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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.
Errors
| Status | Cause |
|---|---|
404 Not Found |
No product with this ID in your organization, or it was deleted. |
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 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 for every field.
Request
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
{
"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. |
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: 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
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.
{
"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
PATCHnormalizesbilling_type. A request withoutbilling_typesets it toone_timeand clearsbilling_intervalandbilling_interval_count. When you update a recurring product, always sendbilling_type,billing_intervalandbilling_interval_countwith the other fields. - Custom fields: send
custom_fields_by_keywith field keys fromGET /custom-fields?entity_type=product. Setting a key tonullclears it. The API rebuildscustom_fields_by_nameandcustom_fields_meta_data. - AI search:
is_embeddable: true(re)indexes the product for AI assistant product search,falseremoves 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. |
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
curl -X DELETE https://integrations.achieveapex.com/products/126 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted product with deleted_at set.
{
"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 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.
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
{
"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
Reservation available slots overview
Source: https://www.achieveapex.com/docs/api-reference/reservation-available-slots
Computes the bookable time slots of a service on one date. Use it before creating a reservation: 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 |
The availability object
{
"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
- Hours. If the service has no linked resources, the day runs 08:00–18:00. Otherwise each linked resource's active weekly blocks for that weekday are used (only
resource_id's when it is sent). - Exceptions. An organization-wide
blockedexception closes the day; a resourceblockedexception removes that resource's hours; a resourcespecial_hoursexception replaces them with itsstart_time–end_time. - Slots. Starting at each block's start, a slot every
slot_intervalminutes while start +duration_minutesfits before the block end. Duplicate start times across resources are merged. - Booking window. Slots starting before now +
min_advance_hoursor aftermax_advance_days(service timezone) are dropped.buffer_before_minutes/buffer_after_minutesmust also be free. - Occupancy. Overlapping
pending,confirmedand unexpiredawaiting_paymentreservations count againstslot_capacity(one each, or theirparty_sizewhencapacity_unitispeople) and against each resource'scapacity. A resource is busy when a reservation of any service assigned to it overlaps.max_daily_bookingscloses the day when reached. - 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 runs the same checks again at booking time, so a slot taken in between is rejected with 400.
Related
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 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
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
{
"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:
{
"available": false,
"reason": "This date is blocked",
"slots": [],
"timezone": "America/New_York"
}
See how slots are calculated 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
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 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.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/reservation-booking-links |
List booking links |
GET |
/reservation-booking-links/:id |
Get a booking link |
POST |
/reservation-booking-links |
Create a booking link |
PATCH |
/reservation-booking-links/:id |
Update a booking link |
DELETE |
/reservation-booking-links/:id |
Delete a booking link |
The booking link object
{
"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
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/reservation-booking-links/301 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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. |
settings |
object | No | Free-form object. Default {}. |
tracking_config |
object | No | meta_pixel_id, ga4_measurement_id. |
Request
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.
{
"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. |
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, change the keys you need and send the complete object.
Endpoint
PATCH /reservation-booking-links/:id
Body
Any field of the booking link object 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
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):
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.
{
"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. |
404 Not Found |
No booking link with that ID in your organization. |
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 it with is_active: false instead.
Endpoint
DELETE /reservation-booking-links/:id
Request
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 with deleted_at set.
{
"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
Reservation resource availability overview
Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-availability
Weekly recurring working hours of a resource: 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 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 |
GET |
/reservation-resource-availability/:id |
Get an availability block |
POST |
/reservation-resource-availability |
Create an availability block |
PATCH |
/reservation-resource-availability/:id |
Update an availability block |
DELETE |
/reservation-resource-availability/:id |
Delete an availability block |
The availability object
{
"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 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 a single block.
Related
- Reservation resources
- Reservation resource exceptions: date-specific closures and special hours
- Reservation available slots
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
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/reservation-resource-availability/91001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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 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
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.
{
"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. |
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 except id. Unknown fields return 400. breaks is replaced as a whole.
Request
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/reservation-resource-availability/91001 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted availability object with deleted_at set.
{
"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
Reservation resource exceptions overview
Source: https://www.achieveapex.com/docs/api-reference/reservation-resource-exceptions
Date-specific overrides of the weekly 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 |
GET |
/reservation-resource-exceptions/:id |
Get an exception |
POST |
/reservation-resource-exceptions |
Create an exception |
PATCH |
/reservation-resource-exceptions/:id |
Update an exception |
DELETE |
/reservation-resource-exceptions/:id |
Delete an exception |
The exception object
{
"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 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 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
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:
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/reservation-resource-exceptions/92001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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:
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:
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.
{
"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. |
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 except id. Unknown fields return 400.
Request
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/reservation-resource-exceptions/92001 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted exception object with deleted_at set.
{
"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
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, date exceptions, and are attached to services through service resources.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/reservation-resources |
List resources |
GET |
/reservation-resources/:id |
Get a resource |
POST |
/reservation-resources |
Create a resource |
PATCH |
/reservation-resources/:id |
Update a resource |
DELETE |
/reservation-resources/:id |
Delete a resource |
The resource object
{
"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, 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: weekly hours
- Reservation resource exceptions: blocked dates and special hours
- Reservation service resources: attach resources to services
- Reservations
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 can be used as a filter. Results are limited to the API key's organization automatically.
Request
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/reservation-resources/88 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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 and attach it to services with service resources; 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
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.
{
"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. |
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 except id. Unknown fields return 400. metadata is replaced as a whole.
Request
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.
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/reservation-resources/90 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted resource object with deleted_at set.
{
"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
Reservation service resources overview
Source: https://www.achieveapex.com/docs/api-reference/reservation-service-resources
A service resource links a resource to a service 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 |
GET |
/reservation-service-resources/:id |
Get a service resource |
POST |
/reservation-service-resources |
Create a service resource |
PATCH |
/reservation-service-resources/:id |
Update a service resource |
DELETE |
/reservation-service-resources/:id |
Delete a service resource |
The service resource object
{
"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. Required on create. |
resource_id |
integer | Resource. 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 the service offers.
Related
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 or GET /reservation-resources?id[$in][]=....
Request
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
{
"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
}
]
}
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
curl https://integrations.achieveapex.com/reservation-service-resources/7001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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 ID. |
resource_id |
integer | Yes | Resource 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
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.
{
"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. |
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 except id. Unknown fields return 400.
Request
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.
{
"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. |
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
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 with deleted_at set.
{
"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
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 belongs to one service.
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/reservation-services |
List services |
GET |
/reservation-services/:id |
Get a service |
POST |
/reservation-services |
Create a service |
PATCH |
/reservation-services/:id |
Update a service |
DELETE |
/reservation-services/:id |
Delete a service |
The service object
{
"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 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. |
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. |
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
- Reservation service resources: which resources a service needs
- Reservation available slots
- Reservation booking links
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 can be used as a filter. Results are limited to the API key's organization automatically.
Request
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
{
"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 (shortened above).
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
curl https://integrations.achieveapex.com/reservation-services/12 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the full service object.
{
"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. |
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 except id, created_at, updated_at and deleted_at can also be sent.
Request
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.
{
"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. |
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 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
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.
{
"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. |
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 it with is_active: false instead.
Endpoint
DELETE /reservation-services/:id
Request
curl -X DELETE https://integrations.achieveapex.com/reservation-services/12 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted service object with deleted_at set.
{
"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
Reservations overview
Source: https://www.achieveapex.com/docs/api-reference/reservations
A reservation books a contact into a reservation service 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 |
GET |
/reservations/:id |
Get a reservation |
POST |
/reservations |
Create a reservation |
PATCH |
/reservations/:id |
Update a reservation |
DELETE |
/reservations/:id |
Delete a reservation |
Typical flow
- List services (
is_active=true). - Get available slots for a service and date.
- Create the reservation with the slot
start_datetime. - Update it 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 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
{
"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 and resource the full resource object (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 booked. Required on create. |
contact_id |
integer | Contact 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): 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 where the booking originated. |
deal_id |
integer | null | Related deal. |
company_id |
integer | null | Related company. |
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 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), 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
completedawards loyalty points or stamps to the contact when the organization has an active loyalty program. - Reminders: reminder emails are sent automatically before
start_datetimeaccording to the organization's reservation settings and recorded inreminders_sent. - No email is sent for reservations in
cancelledorno_showstatus.
Related
- Reservation services
- Reservation available slots
- Reservation resources
- Reservation booking links
- Contacts
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 can be used as a filter. Results are limited to the API key's organization automatically.
Request
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:
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
{
"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 (shortened above).
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
curl https://integrations.achieveapex.com/reservations/5001 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |
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 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 to book. Must be active. |
contact_id |
integer | Yes | Contact the booking is for. |
start_datetime |
string (date-time) | Yes | Start, as service wall-clock time (see date and time format). |
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). |
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. |
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 for every field.
Request
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 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.
{
"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 leastmin_advance_hoursaway. - When
max_advance_days> 0: the date is at mostmax_advance_daysahead. - When
max_daily_bookingsis set: fewer than that manypending/confirmedreservations exist for the service that day. - When
capacity_modeisper_slot: fewer thanslot_capacitypending/confirmedreservations overlap the time (only those onpreferred_resource_idwhen it is sent). - For each linked resource: the resource has a weekly availability block covering the time on that weekday, no
blockedexception that day, and enough freecapacity.requiredresources must pass;optionalones are skipped when busy;any_availablepicks any active resource of the sameresource_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 forcancelledorno_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. |
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. 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:
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:
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:
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, with service, contact and assigned_resources.
{
"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
statustocompletedawards loyalty points or stamps to the contact (once per reservation) when the organization has an active loyalty program;payment_amountcounts 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. |
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 its status to cancelled instead.
Endpoint
DELETE /reservations/:id
Request
curl -X DELETE https://integrations.achieveapex.com/reservations/5001 \
-H "x-api-key: YOUR_API_KEY"
Response
Returns the deleted reservation object with deleted_at set.
{
"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
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 |
GET |
/support-tickets/:id |
Get a ticket |
POST |
/support-tickets |
Create a ticket |
PATCH |
/support-tickets/:id |
Update a ticket |
DELETE |
/support-tickets/:id |
Delete a ticket |
The support ticket object
{
"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 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 (type ticket). |
pipeline_stage_id |
integer | null | Stage 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
- Pipelines and Pipeline stages (type
ticket) - Upload URLs (type
support-ticket-file) - Errors
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 can be used as a filter with the standard operators.
| 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
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
{
"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 (shortened here).
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
curl https://integrations.achieveapex.com/support-tickets/123 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 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. |
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
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:
{
"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. |
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. 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
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:
{
"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. |
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
curl -X DELETE https://integrations.achieveapex.com/support-tickets/125 \
-H "x-api-key: YOUR_API_KEY"
Response
The deleted support ticket with deleted_at set:
{
"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. |
Support ticket errors
Source: https://www.achieveapex.com/docs/api-reference/support-tickets/errors
Support ticket endpoints use the standard error format. 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. |
{
"name": "NotFound",
"message": "No record found for id '999'",
"code": 404,
"className": "not-found"
}
Upload URLs
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 |
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 and message attachments. |
conversation-predefined-message |
organization_id |
Media of 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. |
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
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. |
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
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
{
"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
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
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 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 |
GET |
/whatsapp-channels/:id |
Get a WhatsApp number |
The WhatsApp channel object
{
"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. |
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. 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.
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.
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
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
{
"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 (shortened here).
Notes
- Members restricted to some channel accounts only see the numbers they have access to.
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
curl https://integrations.achieveapex.com/whatsapp-channels/12 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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 (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
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. 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 |
GET |
/whatsapp-channel-message-templates/:id |
Get a WhatsApp template |
The template object
{
"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 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). |
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
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
{
"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.
Errors
| Status | When |
|---|---|
400 Bad Request |
$client[sync] without a single whatsapp_channel_id, or Meta returned an error while syncing. |
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
curl https://integrations.achieveapex.com/whatsapp-channel-message-templates/812 \
-H "x-api-key: YOUR_API_KEY"
Response
{
"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. |