Antavo Customers API

openapi: 3.2.0
info:
  title: Antavo Customers API
  version: '1.0'
  description: 'Operations tagged Customers across 3 of this provider''s published API definitions: antavo-customer-openapi.yml, antavo-display-openapi.yml, antavo-loyalty-read-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.staging.antavo.com
  description: The Antavo staging environment
- url: https://read-api.<environment>.antavo.com
tags:
- name: Customers
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
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /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
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /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
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /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
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/-/verify/:
    get:
      tags:
      - Customers
      summary: Verify credentials provided during registration
      description: 'This endpoint is used to confirm registration.


        A successful verification will change the status of the customer to `active` and enable them to log in and engage with the loyalty program. Failure will leave the customer in an `inactive` status.


        The verification process occurs using a token.


        This requires the Custom login module with the verification option enabled (disabled by default).

        '
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: The access token from the link, provided in the verfication email used to verify the customer.
          example: ZTM4Mjk4YTk5ZTkyZTg5NWE5N2UzNWViNjlhNGYyZDMxZmZkNGU1M2ExOGNmZTNiOWE3Y2YzZmE2ZTMyNjdiOQ.eyJjdXN0b21lciI6Im5vdF9hX3ZhbGlkX2N1c3RvbWVyIiwiZXhwaXJlc19hdCI6ImxvbmdfYWdvIn0
      - name: redirect_url
        in: query
        schema:
          type: string
          description: If provided, the user will be redirected to this URL after successful confirmation.
      responses:
        '200':
          description: Customer registration confirmed successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                fail:
                  summary: Invalid token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This request token is not valid
                fail2:
                  summary: Used Token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This token has already been used
                fail3:
                  summary: Expired token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This token has been expired
                fail4:
                  summary: Deactivated token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This token is already deactivated
      deprecated: false
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/{customer_id}/opt-in:
    post:
      tags:
      - Customers
      summary: Create a new customer with log-in credentials
      description: "This endpoint creates customer within Antavo according to the specified opt-in parameters stated in the body. \n\nThis interface is primarily used as a customer-driven registration process which also generates login credentials, enabling the new customer to log into Antavo systems. This endpoint complements the [opt-in](https://developers.antavo.com/docs/api-events#opt_in) event.\n"
      parameters:
      - name: customer_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
          example: 280e674c-c4ea-4a30-987a-d9267d1a5018
      requestBody:
        description: Customer opt-in parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Optin'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer_2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                fail:
                  summary: Customer already exists
                  value:
                    type: BadRequestException
                    code: 0
                    message: Customer already exists
                fail2:
                  summary: Missing Path parameter
                  value:
                    type: BadRequestException
                    code: 0
                    message: 'Missing path param: customer_id'
      deprecated: false
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/-/login:
    post:
      tags:
      - Customers
      summary: Log in a specific customer to Antavo
      description: 'This endpoint logs the specified customer into Antavo and a successful login returns the customer object.


        The username attribute can be specified in the Antavo Management UI from any available profile attribute.

        The customer ID can then be accessed and used for subsequent calls using Antavo Display API endpoints.


        A successful log-in will also create a ``daily_login`` event for the customer.

        This event will only be written once to the customer''s event stream per calendar day.


        This requires the Custom login module to be enabled.

        '
      requestBody:
        description: Login request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer_2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                fail:
                  summary: Wrong username/password
                  value:
                    type: BadRequestException
                    code: 0
                    message: Invalid username or password
      deprecated: false
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/-/password/request:
    post:
      tags:
      - Customers
      summary: Request a new password for Antavo login
      description: 'A forgotten password can be reset through this endpoint.

        The username can be set in the Customer login module in the Management UI and can be any customer profile attribute.

        The `url` string is a URL which can be extended with the reset token.

        '
      requestBody:
        description: Password reset request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordRequest'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                fail:
                  summary: Customer not found
                  value:
                    type: BadRequestException
                    code: 0
                    message: Customer not found
      deprecated: false
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /customers/-/password/reset:
    post:
      tags:
      - Customers
      summary: Reset the password of the current customer
      description: 'This provides a customer interface for changing a password. The token is captured from the link provided by the password reset email. A simple check is provided to ensure that the two passwords match.

        This requires the Custom login module to be enabled.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordReset'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: The token used for password reset.
                    example: ZTM4Mjk4YTk5ZTkyZTg5NWE5N2UzNWViNjlhNGYyZDMxZmZkNGU1M2ExOGNmZTNiOWE3Y2YzZmE2ZTMyNjdiOQ.eyJjdXN0b21lciI6Im5vdF9hX3ZhbGlkX2N1c3RvbWVyIiwiZXhwaXJlc19hdCI6ImxvbmdfYWdvIn0
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
              examples:
                fail:
                  summary: Invalid token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This request token is not valid
                fail2:
                  summary: Used Token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This token has already been used
                fail3:
                  summary: Expired token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This token has been expired
                fail4:
                  summary: Deactivated token
                  value:
                    type: BadRequestException
                    code: 0
                    message: This token is already deactivated
                fail5:
                  summary: Non-matching Passwords
                  value:
                    type: BadRequestException
                    code: 0
                    message: Passwords do not match
      deprecated: false
      security:
      - api_key: []
    servers:
    - url: https://api.staging.antavo.com
      description: The Antavo staging environment
  /v1/customers/{customer_id}:
    get:
      operationId: getCustomer
      summary: Retrieve detailed customer data of a single customer
      description: Retrieves a customer by customer ID and returns the data associated with the customer.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/CustomerIdParam'
      responses:
        '200':
          description: Success - Customer data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                    example: success
                  metadata:
                    type: object
                  payload:
                    $ref: '#/components/schemas/CustomerEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Error - Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        5XX:
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://read-api.<environment>.antavo.com
  /v1/customers:
    get:
      operationId: listCustomers
      summary: Retrieve the list of customers
      description: 'Returns a paginated list of customers, including standard customer fields and any custom customer attributes configured in the workspace.

        Results can be filtered and sorted by `created_at` and `status` customer attribute values.

        '
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        style: deepObject
        explode: true
        description: Use the supported fields and operators to filter the results.
        schema:
          $ref: '#/components/schemas/CustomersFilter'
      - name: sort
        in: query
        style: deepObject
        explode: true
        description: 'Sorts results by one or more fields in the specified order. Each field can be used only once.

          When multiple sort instructions are provided, the first field is used as the primary sort field. Each additional field determines the order of results that have the same value for the preceding field.

          Example: `?sort[0][field]=status&sort[0][direction]=asc&sort[1][field]=created_at&sort[1][direction]=desc`

          '
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSortEntry'
      responses:
        '200':
          description: Success - Customer data provided
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - metadata
                - payload
                properties:
                  status:
                    type: string
                    const: success
                  metadata:
                    allOf:
                    - $ref: '#/components/schemas/CollectionMetadata'
                    example:
                      pagination:
                        next: /v1/customers/55e5d4dc2cf1901e688b45d3/customers?offset=0&limit=20
                        previous: null
                  payload:
                    type: object
                    required:
                    - customers
                    properties:
                      customers:
                        type: array
                        items:
                          $ref: '#/components/schemas/CustomerEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        5XX:
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://read-api.<environment>.antavo.com
components:
  schemas:
    Customers:
      type: object
      description: Returns Customer unique id which match the search criteria
      properties:
        id:
          type: string
          description: The unique customer identifier.
          example: 55e5d4dc2cf1901e688b45d3
    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
    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.
                  

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-customers-api-openapi.yml