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

# Search Customers

> Look up an existing customer by email or phone number

Search for an existing customer belonging to your business by email and/or phone number. Use this to look up a Soap `customer_id` before creating a checkout, or to check whether a customer already exists. Results are always scoped to the merchant whose API key is used.

<Note>
  At least one of `email` or `phone_number` must be supplied. When both are provided, the customer must match **both** values (AND semantics). Email matching is case-insensitive; phone numbers are normalized to 10 digits (a leading `+1` and any non-digit characters are stripped).
</Note>

<RequestExample>
  ```bash Curl theme={null}
  curl -G "https://api-sandbox.paywithsoap.com/api/v1/customers/search" \
    -H "Authorization: YOUR_API_KEY" \
    --data-urlencode "email=customer@example.com"
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'
  require 'json'

  uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/customers/search')
  uri.query = URI.encode_www_form(email: 'customer@example.com')

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri.request_uri)
  request['Authorization'] = 'YOUR_API_KEY'

  response = http.request(request)
  puts response.body
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const searchCustomer = async () => {
    try {
      const response = await axios.get('https://api-sandbox.paywithsoap.com/api/v1/customers/search', {
        params: {
          email: 'customer@example.com'
        },
        headers: {
          'Authorization': 'YOUR_API_KEY'
        }
      });

      console.log(response.data);
    } catch (error) {
      console.error(error);
    }
  };

  searchCustomer();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api-sandbox.paywithsoap.com/api/v1/customers/search"

  headers = {
      "Authorization": "YOUR_API_KEY"
  }

  params = {
      "email": "customer@example.com"
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Match found theme={null}
  {
    "results": [
      {
        "id": "cus_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK",
        "internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b",
        "email": "customer@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone_number": "8008001234",
        "created_at": "2026-05-31T18:26:43.069Z"
      }
    ]
  }
  ```

  ```json No match theme={null}
  {
    "results": []
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /api/v1/customers/search
openapi: 3.1.0
info:
  title: Soap API
  description: >-
    API documentation for Soap - AI-native payments infrastructure for complex,
    compliance-heavy payment flows
  license:
    name: MIT
  version: 1.4.0
servers:
  - url: https://api-sandbox.paywithsoap.com
security:
  - bearerAuth: []
paths:
  /api/v1/customers/search:
    get:
      tags:
        - Customers
      summary: Search customers by email and/or phone number
      parameters:
        - name: email
          in: query
          required: false
          description: >-
            Customer email. Case-insensitive. At least one of `email` or
            `phone_number` must be supplied.
          schema:
            type: string
            example: john@acme.com
        - name: phone_number
          in: query
          required: false
          description: >-
            US phone number. Non-digit characters and a leading +1 are stripped;
            the normalized form must be 10 digits. At least one of `email` or
            `phone_number` must be supplied.
          schema:
            type: string
            example: '8008001234'
      responses:
        '200':
          description: Search results. Always returns a `results` array, possibly empty.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique Soap identifier for the customer.
                          example: cus_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK
                        internal_id:
                          type: string
                          nullable: true
                          description: >-
                            Your own reference for the customer, if provided at
                            creation.
                          example: 3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b
                        email:
                          type: string
                          example: john@acme.com
                        first_name:
                          type: string
                          example: John
                        last_name:
                          type: string
                          example: Doe
                        phone_number:
                          type: string
                          example: '8008001234'
                        created_at:
                          type: string
                          format: date-time
                          example: '2026-05-31T18:26:43.069Z'
        '401':
          description: Unauthorized - Invalid or missing API key
        '422':
          description: >-
            Invalid search parameters — neither `email` nor `phone_number`
            provided, or an unparseable phone number.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type: string
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your API key

````