> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get customer by document or phone

> Look up a customer by document number, phone, or both within your account. When both are sent, the customer must match both filters. Requires a SERVER API key; CLIENT API keys cannot access this endpoint.

Requires a **SERVER** API key. Pass `document_number`, `phone`, or both. When both are sent, the customer must match both. **CLIENT** keys receive `403`.


## OpenAPI

````yaml GET /customers
openapi: 3.0.1
info:
  title: Masivo's REST API
  description: Learn how to use Masivo's REST API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.masivo.ai/api/storefront/v1
security:
  - bearerAuth: []
paths:
  /customers:
    get:
      description: >-
        Look up a customer by document number, phone, or both within your
        account. When both are sent, the customer must match both filters.
        Requires a SERVER API key; CLIENT API keys cannot access this endpoint.
      parameters:
        - in: query
          name: document_number
          description: >-
            The customer's document number (exact match). When phone is also
            sent, the customer must match both.
          required: false
          schema:
            type: string
            maxLength: 50
        - in: query
          name: phone
          description: >-
            The customer's phone. Matched by digits only (10 to 15). Spaces,
            dashes, and + are ignored. Any country code is accepted. When
            document_number is also sent, the customer must match both.
          required: false
          schema:
            type: string
            example: +593 99 123 4567
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/StoreFrontCustomerByDocument'
        '403':
          description: CLIENT API key not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    StoreFrontCustomerByDocument:
      type: object
      required:
        - customer_id
        - customer
        - wallet
      properties:
        customer_id:
          type: string
          description: The customer unique identifier in your system
        customer:
          $ref: '#/components/schemas/Customer'
        wallet:
          $ref: '#/components/schemas/Wallet'
    Error:
      required:
        - error
        - details
      type: object
      properties:
        error:
          type: string
        details:
          type: string
    Customer:
      type: object
      required:
        - id
        - name
        - email
        - registration_date
      properties:
        id:
          type: string
          description: Your customer unique identifier
        status:
          description: The status of the customer
          type: string
          enum:
            - ACTIVE
            - INACTIVE
        is_anonymous:
          description: Whether the customer is anonymous
          type: boolean
          default: false
        name:
          description: The full name of the customer
          type: string
          example: John Smith
        email:
          description: The email of the customer
          type: string
          format: email
        gender:
          description: The gender of the customer
          type: string
          nullable: true
          enum:
            - MALE
            - FEMALE
        dob:
          description: The date of birth of the customer
          type: string
          nullable: true
          format: date-time
        document_type:
          description: The document type of the customer
          type: string
          nullable: true
        document_number:
          description: The document number of the customer
          type: string
          nullable: true
          maxLength: 50
        country:
          description: The country of the customer
          type: string
          nullable: true
          maxLength: 100
        phone:
          description: >-
            The customer's phone number in international format. Required for
            WhatsApp delivery.
          type: string
          nullable: true
          example: +593 99 123 4567
        phone_verified:
          description: Whether the customer's phone number is verified
          type: boolean
          default: false
        registration_date:
          description: The date when the customer was registered
          type: string
          format: date-time
        tier_id:
          description: The id of the tier the customer currently belongs to
          type: string
          format: uuid
        tags:
          type: object
          description: Include your conditions customer tags here
        consent:
          $ref: '#/components/schemas/Consent'
          description: The customer's consent preferences
          nullable: true
        metrics:
          description: The metrics of the customer
          type: object
        metadata:
          description: The metadata of the customer
          type: object
    Wallet:
      type: object
      properties:
        id:
          type: string
          description: The wallet internal unique identifier
          format: uuid
        owner_id:
          type: string
          description: The customer internal unique identifier
          format: uuid
        lines:
          $ref: '#/components/schemas/Lines'
          description: >-
            Each line represents a batch of a given reward_id that expires at
            the same time
        totals:
          type: array
          description: The wallet totals by reward
          items:
            type: object
            properties:
              total:
                type: number
                description: The total amount of the reward
                example: 127.6
              reward_id:
                type: string
                description: The reward id of the total
                format: uuid
              expiration_date:
                type: string
                description: The expiration date of the total
                format: date-time
              reward:
                $ref: '#/components/schemas/Reward'
    Consent:
      type: object
      required:
        - consent_string
      properties:
        version:
          type: string
          description: IAB TCF version
          example: '2.0'
        consent_timestamp:
          type: string
          format: date-time
          description: The timestamp when consent was given
        customer_id:
          type: string
          description: The customer unique identifier
        purposes:
          $ref: '#/components/schemas/ConsentPurposes'
        vendors:
          type: object
          description: 'Vendor consent mapping (vendor_id: boolean)'
          additionalProperties:
            type: boolean
          example:
            vendor_123: true
            vendor_456: false
        consent_string:
          type: string
          description: >-
            IAB TCF consent string in base64url format, starting with 'CO',
            minimum 20 characters, maximum 500 characters
          example: COvFyGBOvFyGBAbAAAENAPCAAOAAAAAAAAAAAEEUACCKAAA
          minLength: 20
          maxLength: 500
          pattern: ^CO[A-Za-z0-9_-]+$
    Lines:
      type: array
      items:
        $ref: '#/components/schemas/Line'
    Reward:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: The reward internal unique identifier
              format: uuid
        - $ref: '#/components/schemas/RewardInsert'
    ConsentPurposes:
      type: object
      properties:
        behavioral_campaigns:
          type: boolean
          description: Consent for behavioral campaigns
        coupon_campaigns:
          type: boolean
          description: Consent for coupon campaigns
        punchcard_campaigns:
          type: boolean
          description: Consent for punchcard campaigns
        email_marketing:
          type: boolean
          description: Consent for email marketing
        push_notifications:
          type: boolean
          description: Consent for push notifications
        whatsapp_marketing:
          type: boolean
          description: Consent for WhatsApp marketing messages
        audience_marketing:
          type: boolean
          description: Consent to belong to marketing audiences
        inapp_messages:
          type: boolean
          description: Consent for in-app messages
        news_feed:
          type: boolean
          description: Consent for news feed cards
        link_tracking:
          type: boolean
          description: Consent for link tracking
    Line:
      type: object
      properties:
        amount:
          type: number
          description: The amount of the line
        reward_id:
          type: string
          description: The reward id of the line
          format: uuid
        campaign_id:
          type: string
          description: The campaign id of the line
          format: uuid
          nullable: true
        brand_id:
          type: string
          description: The id of the brand that originated the line
          format: uuid
          nullable: true
        issued_at:
          type: string
          description: The date when the line was issued
          format: date-time
        expiration_date:
          type: string
          description: The expiration date of the line
          format: date-time
        reservation_expires_at:
          type: string
          description: The reservation expiration date of the line
          format: date-time
          nullable: true
    RewardInsert:
      type: object
      properties:
        brand_id:
          type: string
          description: The brand id of the reward, null if is a global reward
          nullable: true
        account_id:
          type: string
          description: The account id that owns this reward.
          format: uuid
        status:
          type: string
          description: The status of the reward.
          enum:
            - ACTIVE
            - INACTIVE
        team_ids:
          type: array
          description: Team ids associated with this reward.
          items:
            type: string
        template_id:
          type: string
          description: >-
            CMS template id used to structure the reward content, or null when
            no template is selected.
          format: uuid
          nullable: true
        content:
          type: object
          description: CMS content values for the reward.
          additionalProperties: true
        platforms:
          type: array
          description: Platforms where this reward applies.
          items:
            type: string
        labels:
          type: array
          description: Labels used to categorize this reward.
          items:
            type: string
        stores:
          type: array
          description: >-
            Store ids this reward is restricted to. When creating or updating,
            null means no store restriction and a non-empty array restricts the
            reward to those stores.
          items:
            type: string
          nullable: true
        channels:
          type: array
          description: >-
            Channel ids this reward is restricted to. When creating or updating,
            null means no channel restriction and a non-empty array restricts
            the reward to those channels.
          items:
            type: string
          nullable: true
        products:
          type: array
          description: >-
            Product ids this reward is restricted to. When creating or updating,
            null means no product restriction and a non-empty array restricts
            the reward to those products.
          items:
            type: string
          nullable: true
        tiers:
          type: array
          description: >-
            Tier ids allowed to redeem this reward. When creating or updating,
            null or [] means no tier restriction; a non-empty array requires the
            customer's current tier to be included.
          items:
            type: string
            format: uuid
          nullable: true
        name:
          type: string
          description: The name of the reward
        description:
          type: string
          description: The description of the reward
        type:
          type: string
          description: The type of the reward
          enum:
            - POINTS
            - DISCOUNT
            - GIFT_CARD
            - PRODUCT
            - CUSTOM
        conditions:
          $ref: '#/components/schemas/AlternativeCondition'
        attributes:
          description: The attributes of the reward
          oneOf:
            - type: object
              description: The attributes of rewards of type POINTS
              properties:
                conversion_factor:
                  type: number
                  description: How much 1 point is worth in your currency
                  example: 0.1
            - description: The attributes of rewards of type DISCOUNT
              type: object
              properties:
                discount_value:
                  type: number
                  description: The discount value
                  example: 10
                discount_type:
                  type: string
                  description: The type of discount
                  enum:
                    - fixed
                    - percentage
                type:
                  type: string
                  description: The discount will be applied to
                  enum:
                    - shipping
                    - order
                    - product
    AlternativeCondition:
      type: array
      description: OR conditions
      items:
        $ref: '#/components/schemas/CompoundCondition'
    CompoundCondition:
      type: array
      description: AND conditions
      items:
        $ref: '#/components/schemas/Condition'
    Condition:
      type: object
      properties:
        type:
          type: string
          description: The type of the condition
          example: Order Value
        operator:
          type: string
          description: The operator to compare the attribute
          example: grater than
        primitive:
          type: string
          description: The primitive of the value to compare
          enum:
            - string
            - number
            - currency
            - boolean
            - absolute date
            - relative date
            - recurring date
        value:
          oneOf:
            - type: number
              example: 9.95
            - type: string
            - type: boolean
          description: The value to compare
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````