Download a list

GET/api/1/list/{listid}

1	GET/api/1/list/{listid}

Download the specified list from your account.

Parameters

Name	Parameter Type	Allow Multiple	Required/ Optional	Data Type	Description
Authorization:	Header	False	Required	String (Bearer {access token})	Pass the authentication token that was granted when you authorized access.
listid	Path	False	Required	String	The id of list to be updated {listid} in path above).
count	Query	false	optional	String (default="1000", maximum="1000")	Number of records to download.
offset	Query	false	Optional	String (default="0")	Index into the list; where to start downloading.
modbefore	Query	False	Optional	String	Filter on date "modified before timestamp." *
modafter	Query	False	Optional	String	Filter on date "modified after timestamp." *
createdbefore	Query	False	Optional	String	Filter on date "created before timestamp." *
createdafter	Query	False	Optional	String	Filter on date "created after timestamp." *
fields	Query	False	Optional	String (semicolon delimited list)	A semicolon ( ; ) delimited list of fields to display in the returned list. Fields provided should be urlencoded. The "_contact_id_" field is always returned. This parameter is optional. If it is not provided, the whole list will be returned. The query parameter "datequalifiers" cannot be used in conjunction with this option. However, date modified and created timestamp* data can be added while using this option by specifying the field names "__modified_date" and/or "__created_date" in the list of fields to display.
datequalifiers	Query	False	Optional	Boolean `true`/`false`	If specified as "true", the returned list will include timestamps* for each row denoting the dates created and modified. These columns will be headed with the names "__created_date" and "__modified_date". This option cannot be specified in conjunction with the query parameter "fields", and can only be appended to a complete (all fields present) list return.
responseformat	Query	False	Optional	String	Desired response format. Valid values are JSON and CSV with JSON being the default value. If CSV is specified then the first row will be the headers and following rows will be double quoted comma separated values. While JSON is limited to 1,000 list members per API call, CSV can return the entire list even if it is large. For JSON response format the number of fields is limited to 255. For CSV response format the number of fields is unlimited.

* Note: Unix timestamp, in milliseconds. (timestamp converter:example)

Request

The following request examples use the ID for an example list that is available in every developer account:

HTTP

GET /api/1/list/l-ctx HTTP/1.1
Host: restapi.actonsoftware.com
Authorization: Bearer 8a9911f75edbcaa33167831f5346b88
Cache-Control: no-cache

GET /api/1/list/l-ctx HTTP/1.1

Host: restapi.actonsoftware.com

Authorization: Bearer 8a9911f75edbcaa33167831f5346b88

Cache-Control: no-cache

Response

A successful request results in an HTTP 200 response with a JSON object like the following. Note that the JSON lists the ID, any offset, the number of rows, and the headers before listing the data:

{ 
   "listId":"l-ctx",
   "offset":0,
   "count":1,
   "totalCount":1,
   "emailColumn":3,
   "headers":[ 
      "_contact_id_",
      "First Name",
      "Last Name",
      "E-mail Address"
   ],
   "data":[ 
      [ 
         "l-ctx:0,
         "John",
         "Doe",
         "john.doe@act-on.com"
      ]
   ]
}

{

"listId":"l-ctx",

"offset":0,

"count":1,

"totalCount":1,

"emailColumn":3,

"headers":[

"_contact_id_",

"First Name",

"Last Name",

"E-mail Address"

"data":[

[

"l-ctx:0,

"John",

"Doe",

"john.doe@act-on.com"

]

}

Code Examples

curl -X GET https://restapi.actonsoftware.com/api/1/list/l-ctx -H "Authorization: Bearer 12345678-9abc-defg-hijk-lmnopqrs"

1	curl -X GET https://restapi.actonsoftware.com/api/1/list/l-ctx -H "Authorization: Bearer 12345678-9abc-defg-hijk-lmnopqrs"

The java code examples use the java unirest library available at unirest.io. You can also find unirest libraries for node, ruby, php, java, objective c, python, and .net.

Java

package com.acton.api.client.endpoint;

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import org.json.JSONArray;

public class GetListByIDExample 
	{
	static String BASE_URL 		= "https://restapi.actonsoftware.com/";
	static String ACTON_USERNAME 	= "{your username}";
	static String ACTON_PASSWORD 	= "{your password}";
	static String CLIENT_ID 	= "{your client id/key}";
	static String CLIENT_SECRET 	= "{your client secret}";

	public static void main(String[] args) 
		{
		try 	{
			String access_token = getAccessToken();
			Unirest.setDefaultHeader("Authorization", "Bearer " + access_token);
			printListHeaders(); 
        		} 
		catch (UnirestException e) 
			{
			e.printStackTrace();
        		}
    		}

	/**
	  * This method uses Download a List endpoint 
	  * and prints all the headers of the List
	  */

	private static void printListHeaders() throws UnirestException 
		{
		// Get the list with id "l-ctx"
		HttpResponse listResponse = Unirest.get(BASE_URL + "/api/1/list/l-ctx").asJson();
		// Get headers as array
		JSONArray headers =listResponse.getBody().getObject().getJSONArray("headers");
		// Iterate thorough all the headers and print
		for (int i=0;i&lt;headers.length();i++)
			System.out.println(headers.getString(i));
    		}

	/**
	  * This is an util method to get access token
          */

	private static String getAccessToken() throws UnirestException 
		{
		// POST to token url with password grant_type to get token.

		HttpResponse jsonResponse = Unirest.post(BASE_URL + "token")
			.header("accept", "application/json")
			.field("grant_type", "password")
			.field("username", ACTON_USERNAME)
			.field("password", ACTON_PASSWORD)
			.field("client_id", CLIENT_ID)
			.field("client_secret", CLIENT_SECRET)
			.asJson();
		// Strip access_token from response and return it.
		return jsonResponse.getBody().getObject().getString("access_token");
    		}
	}

package com.acton.api.client.endpoint;

import com.mashape.unirest.http.HttpResponse;

import com.mashape.unirest.http.JsonNode;

import com.mashape.unirest.http.Unirest;

import com.mashape.unirest.http.exceptions.UnirestException;

import org.json.JSONArray;

public class GetListByIDExample

{

static String BASE_URL = "https://restapi.actonsoftware.com/";

static String ACTON_USERNAME = "{your username}";

static String ACTON_PASSWORD = "{your password}";

static String CLIENT_ID = "{your client id/key}";

static String CLIENT_SECRET = "{your client secret}";

public static void main(String[] args)

{

try {

String access_token = getAccessToken();

Unirest.setDefaultHeader("Authorization", "Bearer " + access_token);

printListHeaders();

}

catch (UnirestException e)

{

e.printStackTrace();

}

/**

* This method uses Download a List endpoint

* and prints all the headers of the List

private static void printListHeaders() throws UnirestException

{

// Get the list with id "l-ctx"

HttpResponse listResponse = Unirest.get(BASE_URL + "/api/1/list/l-ctx").asJson();

// Get headers as array

JSONArray headers =listResponse.getBody().getObject().getJSONArray("headers");

// Iterate thorough all the headers and print

for (int i=0;i<headers.length();i++)

System.out.println(headers.getString(i));

}

/**

* This is an util method to get access token

private static String getAccessToken() throws UnirestException

{

// POST to token url with password grant_type to get token.

HttpResponse jsonResponse = Unirest.post(BASE_URL + "token")

.header("accept", "application/json")

.field("grant_type", "password")

.field("username", ACTON_USERNAME)

.field("password", ACTON_PASSWORD)

.field("client_id", CLIENT_ID)

.field("client_secret", CLIENT_SECRET)

.asJson();

// Strip access_token from response and return it.

return jsonResponse.getBody().getObject().getString("access_token");

}