> ## 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.

# Search contacts

> Search for contacts using specific criteria. This endpoint allows you to find contacts by their unique identifiers: external ID, email, or document number. At least one of these three fields is required.



## OpenAPI

````yaml GET /contacts
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:
  /contacts:
    get:
      description: >-
        Search for contacts using specific criteria. This endpoint allows you to
        find contacts by their unique identifiers: external ID, email, or
        document number. At least one of these three fields is required.
      parameters:
        - in: header
          name: x-account-id
          description: Your account ID
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: email
          description: Contact email address
          schema:
            type: string
            format: email
        - in: query
          name: document_number
          description: Document number
          schema:
            type: string
        - in: query
          name: external_id
          description: External contact ID
          schema:
            type: string
        - in: query
          name: second_last_name
          description: Second last name
          schema:
            type: string
        - in: query
          name: dob
          description: Date of birth
          schema:
            type: string
            format: date
        - in: query
          name: persona_id
          description: Persona ID for unified contacts
          required: false
          schema:
            type: string
            format: uuid
        - in: query
          name: phone
          description: Contact phone number
          required: false
          schema:
            type: string
        - in: query
          name: gender
          description: Contact gender
          required: false
          schema:
            type: string
        - in: query
          name: document_type
          description: Contact document type
          required: false
          schema:
            type: string
        - in: query
          name: first_name
          description: Contact first name
          required: false
          schema:
            type: string
        - in: query
          name: last_name
          description: Contact last name
          required: false
          schema:
            type: string
        - in: query
          name: country
          description: Contact country
          required: false
          schema:
            type: string
        - in: query
          name: city
          description: Contact city
          required: false
          schema:
            type: string
        - in: query
          name: source
          description: Contact source
          required: false
          schema:
            type: string
        - in: query
          name: channel
          description: Contact channel
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No contacts found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: No contacts found
                  details:
                    type: string
                    example: No contacts found
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal validation failed
                  details:
                    type: object
                    properties:
                      issues:
                        type: array
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                              example: custom
                            message:
                              type: string
                              example: >-
                                At least one of the following parameters is
                                required: id, email, or document_number
                            path:
                              type: array
                              items:
                                type: string
                              example:
                                - searchParams
components:
  schemas:
    Contact:
      type: object
      required:
        - id
        - persona_id
        - email
        - document_number
        - document_type
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the contact
        created_at:
          type: string
          format: date-time
          description: Contact creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Contact last update timestamp
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Contact deletion timestamp (soft delete)
        persona_id:
          type: string
          format: uuid
          description: Persona ID for unified contacts
        external_id:
          type: string
          nullable: true
          description: External contact ID
        first_name:
          type: string
          nullable: true
          description: Contact first name
        second_name:
          type: string
          nullable: true
          description: Contact second name
        last_name:
          type: string
          nullable: true
          description: Contact last name
        second_last_name:
          type: string
          nullable: true
          description: Contact second last name
        email:
          type: string
          format: email
          description: Contact email address
        email_verified:
          type: boolean
          default: false
          description: Whether the email is verified
        dob:
          type: string
          format: date
          nullable: true
          description: Date of birth (YYYY-MM-DD)
        gender:
          type: string
          nullable: true
          enum:
            - MALE
            - FEMALE
          description: Contact gender
        country:
          type: string
          nullable: true
          description: Contact country
        city:
          type: string
          nullable: true
          description: Contact city
        phone:
          type: string
          nullable: true
          description: Contact phone number
        is_anonymous:
          type: boolean
          default: false
          description: Whether the contact is anonymous
        source:
          type: string
          nullable: true
          description: Contact source
        channel:
          type: string
          nullable: true
          description: Contact channel
        phone_verified:
          type: boolean
          default: false
          description: Whether the phone is verified
        document_type:
          type: string
          nullable: true
          description: Document type
        document_number:
          type: string
          nullable: true
          description: Document number
        status:
          type: string
          default: ACTIVE
          description: Contact status
        tags:
          type: object
          nullable: true
          description: Custom tags
        addresses:
          type: array
          nullable: true
          description: Contact addresses
          items:
            type: object
            required:
              - street_1
            properties:
              street_1:
                type: string
                description: Street 1
              street_2:
                type: string
                description: Street 2
              street_number:
                type: string
                description: Street number
              reference:
                type: string
                description: Reference
              alias:
                type: string
                description: Alias
              zip_code:
                type: string
                description: Zip code
              city:
                type: string
                description: City
              state:
                type: string
                description: State
              country:
                type: string
                description: Country
        billing_info:
          type: array
          nullable: true
          description: Billing information
          items:
            type: object
            required:
              - document_number
              - document_type
              - legal_name
            properties:
              document_number:
                type: string
                description: Document number
              document_type:
                type: string
                description: Document type
              legal_name:
                type: string
                description: Legal name
              alias:
                type: string
                description: Alias
              street_1:
                type: string
                description: Street 1
              street_2:
                type: string
                description: Street 2
              street_number:
                type: string
                description: Street number
              city:
                type: string
                description: City
              state:
                type: string
                description: State
              country:
                type: string
                description: Country
              zip_code:
                type: string
                description: Zip code
              phone:
                type: string
                description: Phone
              email:
                type: string
                description: Email
        payments:
          type: array
          nullable: true
          description: Payment information
          items:
            type: object
            required:
              - method
            properties:
              method:
                type: string
                enum:
                  - CREDIT
                  - DEBIT
                  - CASH
                  - BANK_TRANSFER
                  - OTHER
              last_four:
                type: string
                description: Last four digits of the card number
              card_holder:
                type: string
                description: Card holder name
              card_brand:
                type: string
                description: Card brand
              alias:
                type: string
                description: Alias for the payment method
              expiry_month:
                type: number
                description: Expiry month
              expiry_year:
                type: number
                description: Expiry year
        data:
          type: object
          nullable: true
          description: >-
            Internal metadata object containing: contact (full payload), order
            (order information extending Order schema with brand_id), and
            identity_resolutions (applied identity resolution rules)
          properties:
            contact:
              type: object
              description: The full contact payload as received
            order:
              nullable: true
              description: >-
                Order information if provided, extends Order schema with
                brand_id
              allOf:
                - $ref: '#/components/schemas/Order'
                - type: object
                  properties:
                    brand_id:
                      type: string
                      nullable: true
                      description: The brand id associated with this order
            identity_resolutions:
              type: array
              description: Applied identity resolution rules
              items:
                type: object
                properties:
                  conditions:
                    type: array
                    description: Resolution rule conditions
                  max_group_size:
                    type: number
                    description: Maximum group size for resolution
                  temporal_limits:
                    type: array
                    description: Temporal limits for resolution
                  description:
                    type: string
                    description: Rule description
                  isDefault:
                    type: boolean
                    description: Whether this is a default rule
    Error:
      required:
        - error
        - details
      type: object
      properties:
        error:
          type: string
        details:
          type: string
    Order:
      type: object
      required:
        - purchase_id
        - value
        - products
        - payment_method
      properties:
        purchase_id:
          type: string
          description: The id of a placed order in your system
        channel_id:
          type: string
          description: >-
            The channel unique identifier in your system. Used to match campaign
            and reward e-commerce channel restrictions.
        store_id:
          type: string
          description: >-
            The store unique identifier in your system. Used to match campaign
            and reward e-commerce store restrictions.
        value:
          type: number
          description: The order total or subtotal
          example: 20.95
        discounted_value:
          type: number
          description: The order total or subtotal after discounts
          example: 10.95
        products:
          type: array
          description: >-
            Products in the order. Product sku values are used to match campaign
            and reward e-commerce product restrictions.
          minimum: 1
          items:
            $ref: '#/components/schemas/OrderProduct'
        shipping:
          $ref: '#/components/schemas/Shipping'
          description: The shipping information of the order
        payment_method:
          type: string
          description: The payment method used in the order
          enum:
            - CREDIT
            - DEBIT
            - CASH
            - BANK_TRANSFER
            - OTHER
        redeem:
          type: array
          description: The rewards to redeem in the order
          items:
            $ref: '#/components/schemas/RedemptionReward'
        metadata:
          type: object
          description: The metadata of the order
    OrderProduct:
      type: object
      required:
        - sku
        - amount
        - value
      properties:
        sku:
          type: string
          description: >-
            The product sku. Used to match campaign and reward e-commerce
            product restrictions.
        amount:
          type: number
          description: The quantity of the product
        value:
          type: number
          description: The total or subtotal of the product
        discounted_value:
          type: number
          description: The total or subtotal of the product after discounts
        redeem:
          type: array
          description: The rewards to redeem in the product
          items:
            $ref: '#/components/schemas/RedemptionReward'
        tags:
          type: object
          description: Include your conditions event tags here
        metadata:
          type: object
          description: Include any additional info here
    Shipping:
      type: object
      properties:
        value:
          type: number
          description: The shipping cost
          example: 3.25
        discounted_value:
          type: number
          description: The shipping cost after discounts
          example: 2.25
        redeem:
          type: array
          description: The rewards to redeem in the shipping
          items:
            $ref: '#/components/schemas/RedemptionReward'
        tags:
          type: object
          description: Include your conditions event tags here
        metadata:
          type: object
          description: Include any additional info here
    RedemptionReward:
      type: object
      properties:
        id:
          type: string
          description: The reward id to redeem
          format: uuid
        amount:
          type: number
          description: The amount of the reward to redeem. (Per product if applicable)
          example: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````