Learn how to use the Vendors API to search vendors as suppliers to a Square seller.
Vendors API

Search for Vendors in a Seller Account Beta release
This is pre-release documentation for an API in public beta and is subject to change.

To search for vendors in a seller account, call the SearchVendors endpoint using a query filter. You can filter the result by the vendor's name, status, or both attributes. The search is based on the prefix matching where the specified filter value is matched against the beginning of each phrase in the targeted property value. For example, the name filter value of Vendor finds a match in vendors whose name might be "Vendor", "Vendor A", or "Vendor123".

To sort the returned vendors, set the name or created_at sorter in the input to the SearchVendors call to have the result sorted by the corresponding sort key in an ascending or descending order.

Link to section
Search for vendors by names

To search for vendors by names, use the name filter to specify part or all of the targeted vendor names.

Link to section
Request: Search for vendors by names

The following example searches for vendors whose name starts with "Vendor":

Search Vendors
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
curl https://connect.squareupsandbox.com/v2/vendors/search \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "name": [
        "Vendor"
      ]
    }
  }'
Try in API Explorer

Link to section
Response: Search for vendors by names

The successful response returns the result as a vendors list as shown:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
  • 74
  • 75
  • 76
  • 77
  • 78
  • 79
  • 80
  • 81
  • 82
  • 83
  • 84
{
    "vendors": [
        {
            "id": "D6PT5UDV6IWTSIYW",
            "created_at": "2021-12-10T19:52:06.103Z",
            "updated_at": "2021-12-10T19:52:06.103Z",
            "name": "Vendor 1",
            "account_number": "12345",
            "version": 1,
            "status": "ACTIVE"
        },
        {
            "id": "BRAIKC6UT3MQGLTZ",
            "created_at": "2021-12-16T01:51:10.95Z",
            "updated_at": "2021-12-16T01:51:10.95Z",
            "name": "Vendor 11a",
            "address": {
                "locality": "New York",
                "administrative_district_level_1": "NY",
                "postal_code": "10003",
                "country": "US"
            },
            "contacts": [
                {
                    "id": "RWHNPSMBIAI3CMXK",
                    "name": "Joe Burrow",
                    "email_address": "[email protected]",
                    "phone_number": "1-212-555-4250",
                    "removed": false,
                    "ordinal": 0
                }
            ],
            "account_number": "123456",
            "version": 1,
            "status": "ACTIVE"
        },
        {
            "id": "CARJMAFUWDYBTPO2",
            "created_at": "2022-01-16T03:57:11.128Z",
            "updated_at": "2022-01-16T03:57:11.128Z",
            "name": "Vendor 2A",
            "contacts": [
                {
                    "id": "IPSTXCGSCXC5HU2P",
                    "name": "Vendor B's Contact",
                    "email_address": "[email protected]",
                    "phone_number": "1-212-555-4251",
                    "removed": false,
                    "ordinal": 0
                }
            ],
            "version": 1,
            "status": "ACTIVE"
        },
        {
            "id": "5VPCRLENAFZXFZNA",
            "created_at": "2022-01-16T03:57:11.205Z",
            "updated_at": "2022-01-16T03:57:11.205Z",
            "name": "Vendor A",
            "address": {
                "address_line_1": "101 Main Street",
                "address_line_2": "Suite 1",
                "locality": "City",
                "administrative_district_level_1": "State",
                "postal_code": "10003",
                "country": "US"
            },
            "contacts": [
                {
                    "id": "HB5S4SB2EXYGKVJ3",
                    "name": "Vendor A's Contact",
                    "email_address": "[email protected]",
                    "phone_number": "1-212-555-4250",
                    "removed": false,
                    "ordinal": 0
                }
            ],
            "account_number": "4025391",
            "note": "a vendor",
            "version": 1,
            "status": "ACTIVE"
        }
    ]
}

In the previous example, the name filter value is Vendor. The result includes Vendor objects named "Vendor 1", "Vendor 11a", "Vendor 2A", and "Vendor A".

If the name filter is as follows, the result includes only objects named "Vendor 1" and "Vendor 11a" because neither "Vendor 2A" nor "Vendor A" match "Vendor 1":

  • 1
  • 2
  • 3
  • 4
  • 5
{
  "filter": {
    "name": ["Vendor 1"]
  }
}

In addition, the string matching is not case-sensitive. You get the same result if specify the name filter as follows:

  • 1
  • 2
  • 3
  • 4
  • 5
{
  "filter": {
    "name": ["vendor 1"]
  }
}

Link to section
Sort searched vendors by creation time

To sort searched vendors by creation time, set the CREATED_AT sorter with either the ascending (ASC) or descending (DESC) order.

Link to section
Request: Sort searched vendors by creation time in ascending order

The following example sorts the searched vendors by creation time in ascending order:

Search Vendors
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
curl https://connect.squareupsandbox.com/v2/vendors/search \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "name": [
        "vendor 1"
      ]
    },
    "sort": {
      "field": "CREATED_AT",
      "order": "ASC"
    }
  }'
Try in API Explorer

Link to section
Response: Sort searched vendors by creation time in ascending order

The successful response returns the result as a vendors list.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
  • 74
{
    "vendors": [
        {
            "id": "D6PT5UDV6IWTSIYW",
            "created_at": "2022-01-10T19:52:06.103Z",
            "updated_at": "2022-01-10T19:52:06.103Z",
            "name": "Vendor 1",
            "account_number": "12345",
            "version": 1,
            "status": "ACTIVE"
        },
        {
            "id": "G47IRHQ2YFWYWY5Z",
            "created_at": "2022-01-14T04:21:03.606Z",
            "updated_at": "2022-01-14T04:21:03.606Z",
            "name": "Vendor 1a",
            "account_number": "12345a",
            "version": 1,
            "status": "ACTIVE"
        },
        {
            "id": "L2CSGWWIGRQZIPLQ",
            "created_at": "2022-01-16T00:11:05.522Z",
            "updated_at": "2022-01-16T00:11:05.522Z",
            "name": "Vendor 123",
            "address": {
                "address_line_1": "505 Electric Ave",
                "address_line_2": "Suite 600",
                "locality": "New York",
                "administrative_district_level_1": "NY",
                "postal_code": "10003",
                "country": "US"
            },
            "contacts": [
                {
                    "id": "JXRHMI4RL47YB7OW",
                    "name": "Joe Burrow",
                    "email_address": "[email protected]",
                    "phone_number": "1-212-555-4250",
                    "removed": false,
                    "ordinal": 0
                }
            ],
            "account_number": "123456",
            "version": 1,
            "status": "ACTIVE"
        },
        {
            "id": "BRAIKC6UT3MQGLTZ",
            "created_at": "2021-12-16T01:51:10.95Z",
            "updated_at": "2021-12-16T01:51:10.95Z",
            "name": "Vendor 11a",
            "address": {
                "locality": "New York",
                "administrative_district_level_1": "NY",
                "postal_code": "10003",
                "country": "US"
            },
            "contacts": [
                {
                    "id": "RWHNPSMBIAI3CMXK",
                    "name": "Joe Burrow",
                    "email_address": "[email protected]",
                    "phone_number": "1-212-555-4250",
                    "removed": false,
                    "ordinal": 0
                }
            ],
            "account_number": "123456",
            "version": 1,
            "status": "ACTIVE"
        }
    ]
}
On this page