---
updatedAt: 2026-04-23T16:36:04.000Z
agentTools:
  projectIndex: https://borderlessapi.readme.io/llms.txt
---

# Retrieve contacts by specific criteria.

## Introduction
This endpoint will provide you a list of all of your contacts - both internal  and external - that meets certain provided criteria.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Contacts API",
    "description": "# Introduction\nborderless™ is a direct bank to bank payment solution with $0 wire fees. We have created a suite of products to streamline your operations such as Mass Payouts, Accept Bank Payments Online and quick B2B payments. The borderless™ GraphQL API allows payout experiences to be customized to your business’ needs. We have built our solutions for marketplaces, small-businesses, enterprises, and dreamers around the world.\n",
    "termsOfService": "https://getborderless.com/legal/",
    "version": "2.4.14",
    "contact": {
      "name": "API Support",
      "url": "https://getborderless.com/contact/",
      "email": "operations@getborderless.com"
    },
    "x-logo": {
      "url": "https://secure.getborderless.com/static/img/borderless-logo.png",
      "altText": "borderless™ - logo - International direct debit"
    },
    "license": {
      "name": "License",
      "url": "https://getborderless.com/legal/"
    }
  },
  "servers": [
    {
      "url": "https://prod.api.getborderless.com",
      "description": "Production Server"
    },
    {
      "url": "https://sandbox.api.getborderless.com",
      "description": "Sandbox Server"
    }
  ],
  "tags": [
    {
      "name": "Internal Contacts",
      "description": "View and update information about your borderless™ Contacts"
    }
  ],
  "paths": {
    "/contacts/search": {
      "post": {
        "tags": [
          "External Contacts"
        ],
        "summary": "Retrieve contacts by specific criteria.",
        "description": "## Introduction\nThis endpoint will provide you a list of all of your contacts - both internal  and external - that meets certain provided criteria.\n## Data Requirements\n\nProvide the following data requirements when sending a POST request to the Search Contacts endpoint. The url of this request contains the following query parameters:\n<div>\n  <style>\n    table {\n      font-size: small;\n    }\n    .required {\n      font-weight: bolder;\n      font-style: italic;\n    }\n    .type {\n      font-style: italic;\n    }\n    .param {\n      font-weight: bolder;\n    }\n  </style>\n  <table>\n    <tr>\n      <th>Parameter</th>\n      <th>Required?</th>\n      <th>Description</th>\n      <th>Type</th>\n    </tr>\n    <tr>\n      <td class=\"param\">searchTerm</td>\n      <td class=\"required\">Yes</td>\n      <td>Search criteria by which matching contact will be returned. You can search contacts by their display name, slug, @handle, name and/or email. </td>\n      <td class=\"type\">String</td>\n    </tr>\n    <tr>\n      <td class=\"param\">page</td>\n      <td class=\"required\">No</td>\n      <td>Positive number that indicates page to be accessed. Must be provided within a range of total pages. </td>\n      <td class=\"type\">Number</td>\n    </tr>\n  </table>\n</div>\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "searchTerm",
            "required": true,
            "description": "Search criteria by which matching contact will be returned. You can search contacts by their display name, slug, @handle, name and/or email.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "required": false,
            "description": "Positive number that indicates page to be accessed. Must be provided within a range of total pages.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search_Contacts_Successful_Return"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Missing the following required fields (I-6013):"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "searchTerm"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "example": "No auth token provided"
                }
              }
            }
          },
          "404": {
            "description": "Server Error"
          }
        }
      }
    },
    "/Contacts/search": {
      "post": {
        "tags": [
          "Internal Contacts"
        ],
        "summary": "Retrieve contacts by specific criteria.",
        "description": "## Introduction\nThis endpoint will provide you a list of all of your contacts - both internal  and external - that meets certain provided criteria.\n## Data Requirements\n\nProvide the following data requirements when sending a POST request to the Search Contacts endpoint. The url of this request contains the following query parameters:\n<div>\n  <style>\n    table {\n      font-size: small;\n    }\n    .required {\n      font-weight: bolder;\n      font-style: italic;\n    }\n    .type {\n      font-style: italic;\n    }\n    .param {\n      font-weight: bolder;\n    }\n  </style>\n  <table>\n    <tr>\n      <th>Parameter</th>\n      <th>Required?</th>\n      <th>Description</th>\n      <th>Type</th>\n    </tr>\n    <tr>\n      <td class=\"param\">searchTerm</td>\n      <td class=\"required\">Yes</td>\n      <td>Search criteria by which matching contact will be returned. You can search contacts by their display name, slug, @handle, name and/or email. </td>\n      <td class=\"type\">String</td>\n    </tr>\n    <tr>\n      <td class=\"param\">page</td>\n      <td class=\"required\">No</td>\n      <td>Positive number that indicates page to be accessed. Must be provided within a range of total pages. </td>\n      <td class=\"type\">Number</td>\n    </tr>\n  </table>\n</div>\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "searchTerm",
            "required": true,
            "description": "Search criteria by which matching contact will be returned. You can search contacts by their display name, slug, @handle, name and/or email.",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "required": false,
            "description": "Positive number that indicates page to be accessed. Must be provided within a range of total pages.",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search_Contacts_Successful_Return"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Missing the following required fields (I-6013):"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "searchTerm"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "example": "No auth token provided"
                }
              }
            }
          },
          "404": {
            "description": "Server Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "Search_Contacts_Successful_Return": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "handle": {
                  "type": "string",
                  "example": "^19236"
                },
                "displayName": {
                  "type": "string",
                  "example": "John Doe"
                },
                "email": {
                  "type": "string",
                  "example": "john@demo.com"
                },
                "clientInternalReference": {
                  "type": "string",
                  "example": ""
                },
                "dateAdded": {
                  "type": "string",
                  "example": "2022-07-27T21:29:09.500Z"
                },
                "contactType": {
                  "type": "string",
                  "example": "EXTERNAL"
                },
                "country": {
                  "type": "string",
                  "example": "CA"
                },
                "currency": {
                  "type": "string",
                  "example": "CAD"
                },
                "accountType": {
                  "type": "string",
                  "example": "PERSONAL"
                },
                "beneStatus": {
                  "type": "string",
                  "example": "APPROVED"
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "totalPages": {
                "type": "number",
                "example": 1
              },
              "currentPage": {
                "type": "number",
                "example": 1
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```