Collect a Buyer's Contact Information

As part of creating custom workflows with the Terminal 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.

Link to section

How Square Terminal displays the data collection screen

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

An animation of the contact information collection screen displayed on the Square Terminal. A buyer is entering an email address.

Link to section

Make a data collection input request

  1. Send a Terminal action POST request using the CreateTerminalAction 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

    The TerminalAction response includes an action_id and a PENDING status.

    { "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.

    A Square Terminal showing a buyer's email address entered in the input field.

    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

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