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:

Contents

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

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

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

Send the key on every request

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

x-api-key: YOUR_API_KEY
Content-Type: application/json
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

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

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

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


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

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:

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.

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

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

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.

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 whatsapp Delivery status reported by WhatsApp: sent, delivered, read, or failed.
messenger_status string messenger Delivery status reported by Messenger, e.g. sent.
delivery_status string | null sms queued, sent, delivered, failed or received.
status string | null playground Message status.
read boolean Whether the message was read in the inbox. Default false.
timestamp string | null Channel timestamp of the message.
media_url string URL of the image, audio, video or document.
media_urls string[] | null sms Media URLs of an MMS.
filename string Original file name of the attachment.
file_name string webchat, playground Original file name of the attachment.
mime_type string MIME type of the attachment.
file_type string | null playground MIME type of the attachment.
file_size integer webchat, playground Attachment size in bytes.
s3_key / s3_path string | null playground Storage key and s3:// path of the attachment.
conversation_file_id string webchat, playground Conversation file of the attachment.
location_latitude / location_longitude string | number whatsapp, instagram Location messages: coordinates.
location_name / location_address string whatsapp, instagram Location messages: place name and address.
revoked boolean | null whatsapp The contact deleted the message in WhatsApp.
edited boolean | null whatsapp The message was edited (by the contact in WhatsApp, or an edited internal note).
message_text_original string | null whatsapp Text before the edit.
order_data object | null whatsapp WhatsApp catalog order sent by the contact.
interactive_data object | null whatsapp Interactive reply (list or button) sent by the contact.
interactive_type string | null whatsapp Type of the interactive reply.
button_data object | null whatsapp Quick-reply button pressed by the contact.
campaign_id integer | null whatsapp, sms Campaign that sent the message.
is_bulk boolean sms Sent by a bulk SMS campaign.
is_echo boolean whatsapp, instagram, sms true on an outgoing message that was not sent from AchieveApex (the native app, Meta Business Suite, the WhatsApp Business app or a third-party tool) and was reported back by the provider.
is_history boolean whatsapp Message imported from the WhatsApp Business app history when the number was connected.
from / to string | null sms Sender and recipient phone numbers.
error_code / error_message string | null sms Provider error when the SMS failed.
error object | null Error details when sending or the AI reply failed.
contact_deleted boolean | null sms The contact was deleted.
meta_contact_first_name / meta_contact_last_name string | null Contact name at the time of the message.
meta_contact_avatar_url string | null Contact avatar.
meta_contact_phone string | null sms Contact phone.
meta_contact_channel_wa_user_id string | null whatsapp Contact's WhatsApp Business-Scoped User ID, when Meta sent one.
user_id integer | null Team member who sent the message.
meta_user_first_name / meta_user_last_name string | null Sender name.
meta_user_avatar_url string | null Sender avatar.
meta_user_role string | null Sender platform role.
ai_assistant_id integer | null AI assistant that wrote the message.
ai_assistant_name string | null Name of that assistant.
ai_model object | null all but sms Model used for the AI reply.
ai_structured_data object | null all but sms Structured output returned with the AI reply.
automation_id / automation_name integer / string | null Automation that sent the message.
automation_execution_id integer | null Automation execution 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:

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

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:

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:

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:

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 WhatsApp Instagram Messenger Webchat
text yes yes yes yes
note yes yes yes no (webchat messages do not accept the internal destination)
image, video, audio yes yes yes yes
document yes yes no yes
file yes no no no
location yes yes no yes
template WhatsApp templates 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

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

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

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

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

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

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

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.

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:

  1. The exact card code (member_code) or referral code (case and spaces are ignored).
  2. An email address (exact match on the contact email) when the value contains @.
  3. A phone number (at least 6 digits), with or without the country code.

A contact can have one card per program, so a lookup can return several cards when the organization has several programs. Add program_id to get only the card of one program.

List and search
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

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


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

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

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

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:

{
  "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:

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

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 Instagram
messenger Messenger
webchat Webchat
sms SMS

An empty or missing list means every channel, including channels connected later.

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

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

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

  1. 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).
  2. Exceptions. An organization-wide blocked exception closes the day; a resource blocked exception removes that resource's hours; a resource special_hours exception replaces them with its start_time–end_time.
  3. Slots. Starting at each block's start, a slot every slot_interval minutes while start + duration_minutes fits before the block end. Duplicate start times across resources are merged.
  4. Booking window. Slots starting before now + min_advance_hours or after max_advance_days (service timezone) are dropped. buffer_before_minutes / buffer_after_minutes must also be free.
  5. Occupancy. Overlapping pending, confirmed and unexpired awaiting_payment reservations count against slot_capacity (one each, or their party_size when capacity_unit is people) and against each resource's capacity. A resource is busy when a reservation of any service assigned to it overlaps. max_daily_bookings closes the day when reached.
  6. Connected calendars. Busy time of calendars linked to the organization, the service or a resource (Google, Outlook, or open CRM activities of a member) removes the slots it overlaps. A calendar that cannot be read blocks its slots and is listed in calendar_errors.

Weekly availability breaks and valid_from/valid_until are honored. Creating a reservation 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

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

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

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

  1. List services (is_active=true).
  2. Get available slots for a service and date.
  3. Create the reservation with the slot start_datetime.
  4. 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

Related

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:

Resources that pass are assigned to the reservation and returned in assigned_resources.

Side effects

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

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

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

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.