---
title: "Get customers"
method: POST
path: "/api/merchant/v2/customers"
tags: ["Customers"]
---

# Get customers

`POST /api/merchant/v2/customers`

Returns all customers who match the given set of filters.

When filtering by Customer Id, every customer who matches the identifier will be returned.

When filtering by Email, because it is unique, one customer will be returned for each matching identifier.

If we cannot find a customer provided, we will not include them in the response.

If none of the customers provided can be found, we will return a 404.

You may send 100 customers per request.

**Scopes:** `customers:read`

**Rate limits:** 300 requests per 5 minutes. Shared across all 'customers' endpoints.

## Request body

- CustomerIdentifierCollectionInput — A collection of identifiers for customers in Mention Me.
  - `identifiers` CustomerIdentifierInterface[], required — Maximum of 100 identifiers.
    - union
      - CustomerEmailIdentifier
        - `type` 'email', required — The type of identifier.
        - `value` string
      - CustomerIdIdentifier
        - `type` 'customerId', required — The type of identifier.
        - `value` string, required

## Response `200`

All customers who matched the identifiers.

- CustomerPayloadCollectionOutput — A collection of customers with their profile data.
  - `data` CustomerPayload[]
    - `customerId` string — The ID of the customer generated by your system.
    - `email` string
    - `firstname` string
    - `surname` string
    - `phoneNumbers` string[]
    - `profileUrl` string
    - `mentionMeCustomerId` integer — Mention Me's unique customer identifier
    - `offers` CollectionOfUserOfferPayloads — A collection of offers which a customer is enrolled to. An offer is active until it either expires, or is archived by you.
      - `active` UserOfferPayload[]
        - `id` integer
        - `description` string
        - `createdDate` string, date-time
        - `expiryDate` string, date-time
        - `situation` string
        - `segment` string
        - `shareLink` string
        - `dashboardLink` string
    - `nps` CollectionOfNpsPayloads — A collection of NPS scores submitted by a customer. The last 5 NPS scores submitted are shown as recent.
      - `recent` NpsPayload[]
        - `answer` integer
        - `feedback` string
        - `createdDate` string, date-time
    - `createdDate` string, date-time
    - `lastPurchaseDate` string, date-time
    - `receivingEmails` boolean
    - `suspectedOfGaming` boolean
    - `metrics` MetricsPayload
      - `successfulReferrals` integer
      - `shareCount` ShareCountPayload
        - `all` integer — The total number of successful shares made by the customer.
        - `byFacebook` integer — Total number of share responses recorded from Facebook.
        - `byFacebookMessenger` integer — Total number of share responses recorded from Facebook Messenger.
        - `byName` integer — Total number of successful shares made through sharing a referrers name at checkout.
        - `byNativeShare` integer — Total number of share responses recorded through the Native Share method. This is the number of successful shares which came from a share made through the native behaviour when sharing links on mobile devices.
        - `byEmailLink` integer — Total number of successful shares recorded from email links.
        - `byWhatsApp` integer — Total number of successful shares recorded from WhatsApp.
      - `firstReferralDate` string, date-time
      - `lastReferralDate` string, date-time
      - `firstShareDate` string, date-time
      - `lastShareDate` string, date-time
    - `segments` SegmentsPayload — Segments generated by Mention Me for a customer. This includes segments to group customers based on their Extended Customer Revenue (ECR), and the referral network they belong to.
      - `ecrStatus` string
      - `ecrActivity` string
      - `networkId` string
      - `predictedEcr` string
  - `errors` CustomerErrorPayloadInterface[] — All the identifiers which resulted in errors.
    - `type` 'email' | 'customerId'
    - `value` string
    - `reason` 'notFound'

## Other responses

- `401` — Required scopes are missing.
- `404` — No customers matched the identifiers.
- `429` — Rate limit exceeded.

---

[API](https://skmtc.net/mention-me/apis/auth-api.md) · [All operations](https://skmtc.net/mention-me/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mention-me/auth-api/revisions/cdad84f071bd/schema)