Collect a Buyer's Contact Information Beta release

Applies to: Terminal APITerminal API

Learn how to display a screen that collects a buyer's contact information on the Square Terminal.

As part of creating custom workflows with the Terminal APITerminal API, you can create a screen workflow that collects a buyer's contact information such as a phone number or email address. You send a Terminal action request of the DATA_COLLECTION type and the Square Terminal displays a screen with an input field, where the buyer provides contact information to submit and be collected for the seller's records.

In the request body, you can edit the title and body text that displays on the data collection screen. You can also specify the data input type to collect from the buyer. Currently supported input types are EMAIL and PHONE_NUMBER.

The following animation shows how the Square Terminal displays the data collection screen for the buyer:

1. Send a Terminal action POST request using the CreateTerminalActionCreateTerminalAction endpoint and specify the DATA_COLLECTION action type. In the data_collection_options body, provide screen text for title and body. For input_type, specify the type of contact information to collect from the buyer (EMAIL or PHONE_NUMBER).

   Create terminal action

   cURL

   Copy

   The Terminal action response includes an action_id and a PENDING status.

   Copy

   Expand

   {
      "action": {
        "id": "termapia:abcdefg1234567",
        "device_id": "R5WNWB5BKNG9R",
        "deadline_duration": "PT5M",
        "status": "PENDING",
        "created_at": "2022-03-09T09:01:19.622Z",
        "updated_at": "2022-03-09T09:03:06.830Z",
        "type": "DATA_COLLECTION",
        "app_id": "sq0ids-abcdefg123456789",
        "data_collection_options": {
          "title": "Sign up",
          "body": "Join our email list to stay up to date",
          "input_type": "EMAIL"
      }
   }

   The Square Terminal displays the data collection screen for the buyer.

   

   After the buyer confirms their contact information, the Terminal action is put in a COMPLETED state and the Square Terminal displays the idle screen.

2. Send a GET request to see the Terminal action that includes the decision.

   Get terminal action

   cURL

   Copy

   The response returns the buyer's information for input_text in the collected_data body.

   Copy

   Expand

   {
     "action": {
       "id": "termapia:abcdefg1234567",
       "device_id": "R5WNWB5BKNG9R",
       "deadline_duration": "PT5M",
       "status": "COMPLETED",
       "created_at": "2022-03-09T09:01:19.622Z",
       "updated_at": "2022-03-09T09:03:06.830Z",
       "type": "DATA_COLLECTION",
       "app_id": "sq0ids-abcdefg123456789",
       "data_collection_options": {
          "title": "Sign up",
          "body": "Join our email list to stay up to date",
          "input_type": "EMAIL",
          "collected_data": { 
            "input_text": "amelia.earhart@example.com"
          }
       }
     }
   }