Testing

Testing Square APIs with Command Line Tools

Learn how to use cURL or PowerShell to test Square APIs.

Backend

Before you start
Permalink Get a link to this section

The API call example in this article creates a new customer. To make the calls, you must have an access token. You can use a testing account access token from the Application Dashboard or your sandbox personal access token to make the example API call.

Note

Data created with sandbox access tokens (e.g., customers, payments) appears in the Sandbox Seller Dashboard.

Data created with production access tokens appears in your Seller Dashboard so exercise care before posting a request.

API test tools
Permalink Get a link to this section

You can send requests to Connect API endpoints using REST-enabled command line tools:

  • cURL: A command line tool and library for getting and posting data with URL syntax that supports HTTP and HTTPS. If you use cURL, you will need to write and edit cURL call parameters. We recommend that you use a text editor. cURL commands can be scripted.

  • Windows PowerShell: An automation and configuration tool that is optimized for dealing with structured data such as JSON. PowerShell incorporates a command line shell, scripting language, and a framework to support cmdlets. The Invoke-RestMethod cmdlet makes API calls using a syntax that is very similar to cURL. Invoke-RestMethod commands can be scripted.

Did you know?

For testing Square APIs, you do not need to run PowerShell with elevated privileges.

Open a terminal window.

On macOS:

  1. Press command + space keys together to open the Spotlight Search dialog.

  2. Type terminal and press Enter

A Terminal window is opened and the command prompt starts in your user directory.

On Linux, type Ctrl + Alt + T to bring up a terminal window.

Step 2: Declare the request parameters
Permalink Get a link to this section

Open a text editor and copy the example code below to set the auth header, and the body declarations. Make sure you replace ACCESS_TOKEN with your access token.

curl https://connect.squareup.com/v2/customers \
 -H 'Content-Type: application/json'           \
 -H 'Authorization: Bearer ACCESS_TOKEN'       \
 -d '{
  "given_name": "Amelia",
  "family_name": "Earhart",
  "email_address": "Amelia.Earhart@example.com",
  "address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "10003",
    "country": "US"
  },
  "phone_number": "1-212-555-4240",
  "reference_id": "YOUR_REFERENCE_ID",
  "note": "#1 best customer"
}'

Step 3: Make a call to the CreateCustomer endpoint
Permalink Get a link to this section

Copy the updated cURL call to the terminal prompt and press enter.

The response contains the new customer with server-assigned ID:

{
    "customer": {
        "id": "SERVER_ASSIGNED_ID",
        "created_at": "2019-03-20T18:47:54.454Z",
        "updated_at": "2019-03-20T18:47:54Z",
        "given_name": "Amelia",
        "family_name": "Earhart",
        "email_address": "Amelia.Earhart@example.com",
        "address": {
            "address_line_1": "500 Electric Ave",
            "address_line_2": "Suite 600",
            "locality": "New York",
            "administrative_district_level_1": "NY",
            "postal_code": "10003",
            "country": "US"
        },
        "phone_number": "1-212-555-4240",
        "reference_id": "YOUR_REFERENCE_ID",
        "note": "#1 best customer",
        "preferences": {
            "email_unsubscribed": false
        },
        "groups": [
            {
                "id": "6VEKB6X1E99V8.REACHABLE",
                "name": "Reachable"
            }
        ],
        "creation_source": "THIRD_PARTY"
    }
}