Search, retrieve, and manage loyalty member profiles - including login, opt-in registration, password reset, verification, account merging, and active-customer counts - while maintaining member privacy.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/antavo-customer-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.0
info:
contact:
email: support@antavo.com
title: Antavo Customers API
version: 1.0.0-oas3
servers:
- url: https://api.staging.antavo.com
description: The Antavo staging environment
paths:
/customers/-/count:
get:
tags:
- Customers
summary: Returns the number of active customers
description: This endpoint returns the number of customers with active status within Antavo.
responses:
'200':
description: Successful retrieval
content:
application/json:
schema:
$ref: '#/components/schemas/Count'
examples:
Success:
value:
active: 24120
/customers/{customer_id}:
get:
tags:
- Customers
summary: Returns detailed customer data using the Antavo unique ID
description: "This endpoint returns detailed information for a specific customer. \n"
parameters:
- name: customer_id
in: path
required: true
description: "Unique customer ID. This can be \n\n* The Antavo unique ID e.g., `280e674c-c4ea-4a30-987a-d9267d1a5018`\n\
* An external ID (requires [configuration](https://developers.antavo.com/docs/customers#external-identifiers)):\
\ `{external_field:external_id_value}`\n"
schema:
type: string
example: 280e674c-c4ea-4a30-987a-d9267d1a501
- name: fields
in: query
required: false
description: "Returns additional optional fields: \n\n* Groups: Returns associated groups (requires\
\ [User groups module](https://docs.antavo.com/docs/user-groups) for selected customer in the\
\ form of an object with the following properties:\n \n - `ID` - integer\n\n - `Name` - string,\
\ optional (not returned for non-existing groups)\n \n - `external_id` - string, optional\
\ (not returned if empty)\n\n* Purchases: A summary of purchase statistics. Options are [here](https://developers.antavo.com/docs/customers#purchases).\n\
\n* Expiring points: A summary of expiration statistics. Options are [here](https://developers.antavo.com/docs/customers#expiring-points).\n\
\n* Expiration points history: An array of dates and number of points that have expired or will\
\ expire. Options are [here](https://developers.antavo.com/docs/customers#expiring-points).\
\ \n"
schema:
type: string
enum:
- groups
- purchases.ytd
- expiring_points
- expiring_points.history
responses:
'200':
description: Successful customer search
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
failed:
summary: Error - search field is empty or missing
value:
code: 160211
message: Empty search criteria
type: BadRequestException
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
failed:
summary: Error - customer not found
value:
code: 160212
message: Customer not found
type: NotFoundException
/customers:
get:
tags:
- Customers
summary: Search Antavo database using customer filters
description: 'This endpoint allows you to search the Antavo database for customers based on specific
criteria and returns the Antavo Customer ID. Note that the filtering is case-sensitive and does
not support partial matches.
The filtering query requires that the filter parameter has been tagged as [searchable](https://docs.antavo.com/customers#add-a-new-field)
in the Antavo Management UI.
'
parameters:
- in: query
name: Filtering
description: 'Customers can be filtered upon any configured customer field (marked as ``searchable``).
Results are case-sensitive and return exact matches.
It''s possible to query multiple customers based on the last update date. Customer IDs are returned
if the ``updated_at`` customer attribute is greater than a specified datetime using the format
``updated_at.gt=<datetime>``.
'
schema:
type: object
example:
first_name: John
updated_at.gt: '2022-01-01'
- name: search
in: query
required: false
description: Perform searches using key fields such as `first_name`, `last_name`, `email`, `mobile_phone`,
or `membership_id`.
schema:
type: string
example: first_name=John
- name: fields
in: query
required: false
description: 'Returns additional optional attributes from the customer object.
**Note**: Separating commas must be percentage encoded for [API signing](/api-signing).
'
schema:
type: string
- name: match
in: query
required: false
description: 'Enables querying specific customer data. Currently only works with the following
attributes: `_id`, `email`, and `membership_id`. Example usage: `&match=exact&membership_id=33492206-ba75-4487-8047-a9d78a135ce9`'
schema:
type: string
enum:
- exact
- name: limit
in: query
description: 'Limits the number of events to be returned in one response. Other values are accessible
by pagination made accessible via the offset.
'
schema:
type: integer
example: 50
default: 100
- name: offset
in: query
description: 'Offsets the starting number of items for pagination.
'
schema:
type: integer
example: 10
default: 0
responses:
'200':
description: Successful customer search
content:
application/json:
schema:
$ref: '#/components/schemas/Customers'
examples:
Success:
value:
id: 280e674c-c4ea-4a30-987a-d9267d1a5018
Success 2:
summary: Success with fields=groups query
value:
id: a280e674c-c4ea-4a30-987a-d9267d1a5018nakin
groups:
- id: 331
name: USA-Department
external_id: AG331
'404':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
fail:
summary: Error - search field is empty or missing
value:
code: 160211
message: Empty search criteria
type: BadRequestException
/customers/{customer_id}/merge:
post:
tags:
- Customers
summary: Merges the current customer into the target account
description: This endpoint permanently merges the current customer into the target account.
parameters:
- name: customer_id
in: path
required: true
description: "Unique customer ID. This can be \n\n* The Antavo unique ID e.g., ``280e674c-c4ea-4a30-987a-d9267d1a5018``\n\
\n* An external ID (requires [configuration](https://developers.antavo.com/docs/customers#external-identifiers)):\
\ ``{external_field:external_id_value}``\n"
example: 280e674c-c4ea-4a30-987a-d9267d1a5018
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
required:
- target
type: object
properties:
target:
type: string
example: a280e674c-de2a-4a30-987a-d9267d1a119bc123
description: "The target account to merge into. This can be \n\n* The Antavo unique\
\ ID e.g., ``280e674c-c4ea-4a30-987a-d9267d1a5018``\n* An external ID (requires [configuration](https://developers.antavo.com/docs/customers#external-identifiers)):\
\ ``{external_field:external_id_value}``\n"
responses:
'200':
description: Merge successful
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: BadRequestException
code: 160216
message: Customer is not active
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: NotFoundException
code: 160212
message: Customer not found
deprecated: false
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
schemas:
Count:
type: object
description: Number of customers
properties:
active:
type: number
description: The number of active customers.
example: 123456
ErrorResponse:
type: object
description: occurred
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
properties:
code:
type: number
description: Error code.
message:
type: string
description: Human-readable error message.
type:
type: string
description: Type of the error.
Customer:
type: object
description: Detailed customer information for a given Customer unique id.
properties:
id:
type: string
description: The unique customer identifier.
example: 55e5d4dc2cf1901e688b45d3
first_name:
type: string
description: Customer's first name.
example: John
last_name:
type: string
description: Customer's last name.
example: Smith
nickname:
type: string
description: Customer's nickname.
example: Johnny
email:
type: string
description: Customer's email address.
example: jsmith@example.com
birth_date:
type: string
pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
description: Customer language code (ISO-639-1 format).
format: date
example: '1969-12-25'
gender:
type: string
description: Customer's date of birth.
example: Male
language:
type: string
description: Customer's gender
example: en
currency:
type: string
description: The ISO 3-Letter Currency Code for the last currency used.
example: GBP
status:
description: The status of the customer.
type: string
example: Active
score:
description: The total number of points ever earned by the customer.
type: number
example: 100
spent:
description: The points spent by the customer.
type: number
example: 20
reserved:
description: The amount of points reserved on bids or discounts.
type: number
example: 0
expired:
description: The number of points expired.
type: number
example: 100
spendable:
description: The amount of points currently spendable.
type: number
example: 50
pending:
description: The number of pending points for non-finalized actions. Typically given when the
purchase is in its refund/return period.
type: number
example: 20
image_url:
description: The URL of the customer profile picture, if it’s available
type: string
example: https://example.com/image.png
optin_at:
description: The unix timestamp of the enrollment of the customer.
type: number
example: 1577836800
last_login_at:
description: The unix timestamp of the last login of the customer.
type: number
example: 1593561600
updated_at:
description: The unix timestamp of the last time customer data was updated.
type: number
example: 1593561623
properties:
$ref: '#/components/schemas/Properties'
purchase_total:
description: The money spent on purchases by the customer since enrolling into the program.
type: number
example: 100
purchase_count:
description: The number of purchases made by the customer since enrolling into the program.
type: number
example: 2
purchase_last_date:
type: string
description: Last time the customer made a purchase since enrolling into the program.
format: date
pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
example: '2020-10-01'
mobile_phone:
type: string
description: The member's mobile phone number.
example: 123 456 789
accounts:
type: array
description: Sorted by ``account_id`` that contains the customer's accounts.
items:
type: object
properties:
id:
type: string
description: The unique identifier of the account.
example: main_account
name:
type: string
description: The label of the account.
example: Main account
earned:
type: number
description: The total numbers of points earned in this account.
example: 1000
spent:
type: number
description: The total number of points spent in this account.
example: 500
pending:
type: number
description: The total number of pending points in this account.
example: 50
reserved:
type: number
description: The total number of reserved points in this account.
example: 200
expired:
type: number
description: The total number of expired points in this account.
example: 50
spendable:
type: number
description: The total number of spendable points in this account.
example: 800
burn_rates:
type: object
description: The currency-dependent burn rates set in the Management UI.
properties:
amount:
type: number
description: The value of the points.
example: 100
points:
type: number
description: The number of points to be burnt.
example: 50
currency:
type: string
description: The selected currency.
example: USD
campaigns:
type: object
description: Tiered campaign-related information.
properties:
id:
type: string
description: The unique identifier of the current tiered campaign.
example: 63772885e9af5b34933d4aa6
occurrences:
type: object
description: Detailed description and data for all the scheduled occurrences configured
in the current tiered campaign.
properties:
id:
type: string
description: The unique identifier of the current occurrence.
example: 662bac7c0e76787c9b75c80b
pending_points:
type: number
description: The number of pending points in the current occurrence.
example: 100
awarded_points:
type: number
description: The number of points awarded the current occurrence.
example: 50
status:
type: string
description: 'The current status of the current occurrence: Values: `active`, `completed`,
`grace period`, `scheduled`.'
example: cactive
start_date:
type: string
description: The start date of the current occurrence.
example: '2022-11-01T07:36:00+01:00'
end_date:
type: string
description: The end date of the the current occurrence.
example: '2022-12-01T07:36:00+01:00'
evaluation_date:
type: string
description: The date when the current occurrence challenge instance was evaluated.
example: '2022-12-01T07:36:00+01:00'
tiers:
type: array
items:
type: object
properties:
id:
type: string
description: The unique identifier of the current tier.
example: tier1
name:
type: string
description: The tier label.
example: Gold
since:
type: string
description: The datetime at which the member joined this tier.
example: '2022-05-02T12:57:41+02:00'
threshold:
type: number
description: The point threshold for joining this tier.
example: 1000
expdate:
type: string
description: The date when the tier expires and the customers' tier is recalculated.
example: '2023-01-11T00:00:00+01:00'
points:
type: number
description: The number of tier-status points the customer has earned. These may not be
the same as the customer's earned points.
example: 1100
points_after_expiration:
type: number
description: The number of points remaining after the current tier has expired.
example: 1000
structure:
$ref: '#/components/schemas/TierStructure'
next:
$ref: '#/components/schemas/TierNext'
groups:
type: array
description: An array of groups which to which the customer belongs.
items:
type: object
properties:
id:
type: number
description: The numerical group ID.
example: 330
name:
type: string
description: The name of the group (not returned for non-existent groups).
example: USA-Department
external_id:
type: string
description: The external ID of the user group, if any.
example: AG331
TierNext:
type: object
description: Information about the next available loyalty tier.
properties:
id:
type: string
description: The unique identifier for the tier.
example: tier2
name:
type: string
description: Name of the next tier.
example: Platinum
points:
type: string
description: Number of points to collect to reach the next tier.
example: 900
TierStructure:
type: object
description: The overall structure in which the current tier is located.
properties:
id:
type: string
description: The unique identifier of the current tier structure.
example: standard_tiers
name:
type: string
description: The tier structure label.
example: Standard tiers
Properties:
type: object
description: Custom attributes you track about the customer. Data returned in this object depends
on profiling questions or custom data recorded by custom events (may require additional modules
enabled).
properties:
city:
type: string
example: London
Customers:
type: object
description: Returns Customer unique id which match the search criteria
properties:
id:
type: string
description: The unique customer identifier.
example: 55e5d4dc2cf1901e688b45d3
security:
- ApiKeyAuth: []
tags:
- name: Customers