> ## Documentation Index > Fetch the complete documentation index at: https://docs.mention-me.com/llms.txt > Use this file to discover all available pages before exploring further. # Get 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. ## OpenAPI ````yaml /openapi/merchant_api.oas.json post /api/merchant/v2/customers openapi: 3.0.0 info: title: Merchant API description: Interact directly with the Mention Me platform using our REST API. termsOfService: https://mention-me.com/help/tnc_f/site contact: name: Mention Me url: https://mention-me.com email: support@mention-me.com version: v2 servers: - url: https://mention-me.com description: Production - url: https://demo.mention-me.com description: Demo security: - Bearer: [] tags: - name: Coupons - name: Customers - name: Referee paths: /api/merchant/v2/customers: post: tags: - Customers summary: Get customers description: >- 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. operationId: post_merchant_api_customers_list requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerIdentifierCollectionInput' responses: '200': description: All customers who matched the identifiers. content: application/json: schema: $ref: '#/components/schemas/CustomerPayloadCollectionOutput' '401': description: Required scopes are missing. content: application/problem+json: schema: $ref: '#/components/schemas/UnauthorisedRFC7807Problem' '404': description: No customers matched the identifiers. content: application/problem+json: schema: $ref: '#/components/schemas/RFC7807Problem' '429': description: Rate limit exceeded. content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsRFC7807Problem' components: schemas: CustomerIdentifierCollectionInput: description: A collection of identifiers for customers in Mention Me. required: - identifiers properties: identifiers: description: Maximum of 100 identifiers. type: array items: $ref: '#/components/schemas/CustomerIdentifierInterface' maxItems: 100 minItems: 1 type: object CustomerPayloadCollectionOutput: description: A collection of customers with their profile data. properties: data: type: array items: $ref: '#/components/schemas/CustomerPayload' maxItems: 100 minItems: 0 errors: description: All the identifiers which resulted in errors. type: array items: $ref: '#/components/schemas/CustomerErrorPayloadInterface' maxItems: 100 minItems: 0 type: object UnauthorisedRFC7807Problem: properties: status: type: integer maximum: 599 minimum: 200 example: 401 type: type: string example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html title: type: string example: Unauthorized detail: type: string example: Missing at least one of the required scopes type: object RFC7807Problem: properties: status: type: integer maximum: 599 minimum: 200 type: type: string example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html title: type: string detail: type: string type: object TooManyRequestsRFC7807Problem: properties: status: type: integer maximum: 599 minimum: 200 example: 401 type: type: string example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html title: type: string example: Too Many Requests detail: type: string example: Rate limit exceeded for Client Id type: object CustomerIdentifierInterface: discriminator: propertyName: type mapping: email: $ref: '#/components/schemas/CustomerEmailIdentifier' customerId: $ref: '#/components/schemas/CustomerIdIdentifier' oneOf: - $ref: '#/components/schemas/CustomerEmailIdentifier' - $ref: '#/components/schemas/CustomerIdIdentifier' CustomerPayload: description: The profile of a customer. properties: customerId: title: >- This will be the merchant's customer ID, which will be much more useful to them as consumers of the data description: The ID of the customer generated by your system. type: string maxLength: 255 minLength: 1 pattern: .*.*?.* example: CUST-1234 email: type: string maxLength: 320 minLength: 1 pattern: .+\@\S+\.\S+ example: email@mention-me.com firstname: type: string maxLength: 255 minLength: 1 pattern: \w example: Jane surname: type: string maxLength: 255 minLength: 1 pattern: \w example: Doe phoneNumbers: type: array items: type: string example: - '+447123456789' - '+447987654321' profileUrl: type: string example: https://mention-me.com/merchant/123/customers/43211234 mentionMeCustomerId: description: Mention Me's unique customer identifier type: integer minimum: 1 example: 987654321 offers: $ref: '#/components/schemas/CollectionOfUserOfferPayloads' nps: $ref: '#/components/schemas/CollectionOfNpsPayloads' createdDate: title: When this customer was first seen. type: string format: date-time lastPurchaseDate: title: When was the most recent purchase date Mention Me have a record of. type: string format: date-time receivingEmails: title: >- Is this customer willing to set to receive emails about the referral program? type: boolean suspectedOfGaming: title: >- Whether there has been suspicious activity and the customer is suspected of gaming to receive rewards. type: boolean metrics: $ref: '#/components/schemas/MetricsPayload' segments: $ref: '#/components/schemas/SegmentsPayload' type: object CustomerErrorPayloadInterface: discriminator: propertyName: reason mapping: notFound: $ref: '#/components/schemas/MissingCustomerErrorPayload' oneOf: - $ref: '#/components/schemas/MissingCustomerErrorPayload' CustomerEmailIdentifier: required: - type properties: type: description: The type of identifier. type: string enum: - email value: type: string default: '' maxLength: 320 minLength: 1 pattern: .+\@\S+\.\S+ type: object CustomerIdIdentifier: required: - type - value properties: type: description: The type of identifier. type: string enum: - customerId value: type: string type: object CollectionOfUserOfferPayloads: description: |- A collection of offers which a customer is enrolled to. An offer is active until it either expires, or is archived by you. properties: active: type: array items: $ref: '#/components/schemas/UserOfferPayload' type: object CollectionOfNpsPayloads: description: |- A collection of NPS scores submitted by a customer. The last 5 NPS scores submitted are shown as recent. properties: recent: type: array items: $ref: '#/components/schemas/NpsPayload' type: object MetricsPayload: properties: successfulReferrals: type: integer default: 0 shareCount: $ref: '#/components/schemas/ShareCountPayload' firstReferralDate: type: string format: date-time lastReferralDate: type: string format: date-time firstShareDate: type: string format: date-time lastShareDate: type: string format: date-time type: object SegmentsPayload: description: >- 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. properties: ecrStatus: type: string example: high ecrActivity: type: string example: lapsed networkId: type: string example: N-123 predictedEcr: type: string example: high type: object MissingCustomerErrorPayload: properties: type: $ref: '#/components/schemas/CustomerIdentifierType' value: type: string reason: $ref: '#/components/schemas/CustomerIdentifierErrorReason' type: object UserOfferPayload: properties: id: type: integer example: '1234' description: type: string example: Referrer gets 20% off. Referee gets 20% off createdDate: type: string format: date-time expiryDate: type: string format: date-time situation: type: string example: postpurchase segment: type: string example: VIP shareLink: type: string example: https://your-brand.mention-me.com/m/ol/1234 dashboardLink: type: string example: https://your-brand.mention-me.com/d/1234 type: object NpsPayload: properties: answer: type: integer maximum: 10 minimum: 0 example: '10' feedback: title: >- Note: this will only serialize the feedback for an {@see Webhooks::NPS_FEEDBACK} webhook type type: string example: Really great service! createdDate: type: string format: date-time type: object ShareCountPayload: properties: all: title: >- This _will not_ always be equal to the sum of the share types we're exposing here, because we're **not** surfacing all of the possible share types available, we're only surfacing the most common ones. description: The total number of successful shares made by the customer. type: integer default: 0 byFacebook: title: Name Share Share Responses. description: Total number of share responses recorded from Facebook. type: integer default: 0 byFacebookMessenger: title: Name Share Share Responses. description: Total number of share responses recorded from Facebook Messenger. type: integer default: 0 byName: title: Name Share Share Responses. description: >- Total number of successful shares made through sharing a referrers name at checkout. type: integer default: 0 byNativeShare: title: Native Share Share Responses. description: >- 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. type: integer default: 0 byEmailLink: title: Email Link Share Responses. description: Total number of successful shares recorded from email links. type: integer default: 0 byWhatsApp: title: WhatsApp Share Responses. description: Total number of successful shares recorded from WhatsApp. type: integer default: 0 type: object CustomerIdentifierType: type: string enum: - email - customerId CustomerIdentifierErrorReason: type: string enum: - notFound securitySchemes: Bearer: type: http description: RFC8725 Compliant JWT bearerFormat: JWT scheme: bearer ````