Lists (1.0.0)

Everything about creating and manipulating contact lists

View List Contacts

Get all contacts in a list

parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	Contact list ID
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page
updated_after	query	integer(int32)	false	Get all contacts updated after a given timestamp.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/lists/{list_id}/contacts

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/lists/{list_id}/contacts'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here's your list of contacts.",
"data": [{"contact_id": 552786,
"list_id": 428,
"phone_number": "+16783270696",
"first_name": "Ellen",
"last_name": "Diaz",
"custom_1": "",
"custom_2": "",
"custom_3": "",
"custom_4": "",
"date_added": "1436157486",
"date_updated": "1436157486",
"fax_number": null,
"organization_name": null,
"email": null,
"address_line_1": null,
"address_line_2": null,
"address_city": null,
"address_state": null,
"address_postal_code": null,
"address_country": null,
"_list_name": "List6eaG4lGIc9"
},
{"contact_id": 552787,
"list_id": 428,
"phone_number": "+16783270697",
"first_name": "Ellen",
"last_name": "Diaz",
"custom_1": "",
"custom_2": "",
"custom_3": "",
"custom_4": "",
"date_added": "1436157925",
"date_updated": "1436157925",
"fax_number": null,
"organization_name": null,
"email": null,
"address_line_1": null,
"address_line_2": null,
"address_city": null,
"address_state": null,
"address_postal_code": null,
"address_country": null,
"_list_name": "List6eaG4lGIc9"
}
]
}

Create New Contact

Create new contact

parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	List id
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

Properties

Name	Type	Required	Restrictions	Description
phone_number	string	true	none	Your phone number in_E.164_format. Must be provided if no fax number or email.
email	string	false	none	Your email. Must be provided if no phone number or fax number.
fax_number	string	false	none	Your fax number. Must be provided if no phone number or email.
first_name	string	false	none	Your first name.
address_line_1	string	false	none	Your street address
address_line_2	string	false	none	none
address_city	string	false	none	Your nearest city
address_state	string	false	none	Your current state
address_postal_code	string	false	none	Your current postcode
address_country	string	false	none	Your current country
organization_name	string	false	none	Your organisation name
custom_1	string	true	none	none
custom_2	string	false	none	none
custom_3	string	false	none	none
custom_4	string	false	none	none
last_name	string	false	none	Your last name

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/lists/{list_id}/contacts

Request samples

application/json

{"phone_number": "3724763278",
"first_name": "test",
"last_name": "test",
"custom_1": "t",
"custom_2": "e",
"custom_3": "s",
"custom_4": "t",
"date_added": null,
"fax_number": null,
"organization_name": null,
"email": null,
"address_line_1": "x",
"address_line_2": null,
"address_city": null,
"address_state": null,
"address_postal_code": null,
"address_country": "AU"
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here's your list of contacts.",
"data": {"contact_id": 552786,
"list_id": 428,
"phone_number": "+16783270696",
"first_name": "John",
"last_name": "Doe",
"custom_1": "Custom 1",
"custom_2": "Custom 2",
"custom_3": "Custom 3",
"custom_4": "Custom 4",
"date_added": "2015-07-05T14:51:26Z",
"date_updated": "2015-07-05T14:51:26Z",
"fax_number": "+61477141888",
"organization_name": "Awesome Company",
"email": "john@doe.com",
"address_line_1": "1554 Buffalo Creek Road",
"address_line_2": null,
"address_city": "Nashville",
"address_state": "TN",
"address_postal_code": "37214",
"address_country": "US",
"_list_name": "List6eaG4lGIc9"
}
}

Copy Contact to List

Copy contact to another list

Copy contact to another list

Parameters

Parameter	In	Type	Required	Description
from_list_id	path	integer(int32)	true	List ID for list that contains contact.
contact_id	path	integer(int32)	true	Contact ID
to_list_id	path	integer(int32)	true	List ID for list you want to copy contact to.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

from_list_id required	string
contact_id required	string
to_list_id required	string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/lists/{from_list_id}/contacts/{contact_id}/copy/{to_list_id}

Request samples

application/json

""

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Contact #1 has been copied to List #429",
"data": {"contact_id": 552786,
"list_id": 428,
"phone_number": "+16783270696",
"first_name": "John",
"last_name": "Doe",
"custom_1": "Custom 1",
"custom_2": "Custom 2",
"custom_3": "Custom 3",
"custom_4": "Custom 4",
"date_added": "2015-07-05T14:51:26Z",
"date_updated": "2015-07-05T14:51:26Z",
"fax_number": "+61477141888",
"organization_name": "Awesome Company",
"email": "john@doe.com",
"address_line_1": "1554 Buffalo Creek Road",
"address_line_2": null,
"address_city": "Nashville",
"address_state": "TN",
"address_postal_code": "37214",
"address_country": "US",
"_list_name": "List6eaG4lGIc9"
}
}

Transfer Contact to List

Transfer contact to another list

Transfer contact to another list

Parameters

Parameter	In	Type	Required	Description
from_list_id	path	integer(int32)	true	List ID for list that contains contact.
contact_id	path	integer(int32)	true	Contact ID
to_list_id	path	integer(int32)	true	List ID for list you want to transfer contact to.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

from_list_id required	string
contact_id required	string
to_list_id required	string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/lists/{from_list_id}/contacts/{contact_id}/transfer/{to_list_id}

Request samples

application/json

""

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Contact #1 has been transferred to List #429",
"data": {"contact_id": 552786,
"list_id": 428,
"phone_number": "+16783270696",
"first_name": "John",
"last_name": "Doe",
"custom_1": "Custom 1",
"custom_2": "Custom 2",
"custom_3": "Custom 3",
"custom_4": "Custom 4",
"date_added": "2015-07-05T14:51:26Z",
"date_updated": "2015-07-05T14:51:26Z",
"fax_number": "+61477141888",
"organization_name": "Awesome Company",
"email": "john@doe.com",
"address_line_1": "1554 Buffalo Creek Road",
"address_line_2": null,
"address_city": "Nashville",
"address_state": "TN",
"address_postal_code": "37214",
"address_country": "US",
"_list_name": "List6eaG4lGIc9"
}
}

Remove Opted Out Contacts

Remove all opted out contacts

Parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	Your list id
opt_out_list_id	path	integer(int32)	true	Your opt out list id

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id required	string
opt_out_list_id required	string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/lists/{list_id}/remove-opted-out-contacts/{opt_out_list_id}

Request samples

application/json

""

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Optout contacts has been deleted.",
"data": {"deleted": 6
}
}

View Lists

Get all contact lists

Parameters

Parameter	In	Type	Required	Description
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/lists

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/lists'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here are your data.",
"data": {"total": 0,
"per_page": 10,
"current_page": 1,
"last_page": 2,
"next_page_url": "https://api.clicksend.com/v3/lists?page=2",
"prev_page_url": "https://api.clicksend.com/v3/lists?page=1",
"from": 1,
"to": 10,
"data": [{"list_id": 428,
"list_name": "ListCT3QrVL4od",
"list_email_id": "KB0LHD6WXFVHZWTR",
"_contacts_count": 0
},
{"list_id": 429,
"list_name": "ListCT3QrVL4od",
"list_email_id": "KB0LHD6WXFVHZWTR",
"_contacts_count": 0
}
]
}
}

Create List

Create new contact list

Parameters

Parameter	In	Type	Required	Description
list_name	body	string	true	Your contact list name

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/lists

Request samples

application/json

{"list_name": "test"
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "New list has been created.",
"data": {"list_id": 428,
"list_name": "ListCT3QrVL4od",
"list_email_id": "KB0LHD6WXFVHZWTR",
"_contacts_count": 0
}
}

View Secific List

Get specific contact list

Parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	List ID

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/lists/{list_id}

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/lists/{list_id}'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here are your data.",
"data": {"list_id": 428,
"list_name": "ListCT3QrVL4od",
"list_email_id": "KB0LHD6WXFVHZWTR",
"_contacts_count": 0
}
}

Update List

Update specific contact list

Parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	Your list id
list_name	body	string	true	Your new list name

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/lists/{list_id}

Request samples

application/json

{"list_name": "test"
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "List #439 has been updated.",
"data": {"list_id": 428,
"list_name": "ListCT3QrVL4od",
"list_email_id": "KB0LHD6WXFVHZWTR",
"_contacts_count": 0
}
}

Delete List

ListsByListIdDelete

Delete a specific contact list

Parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	List ID

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

delete/v3/lists/{list_id}

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request DELETE \

'https://rest.clicksend.com/v3/lists/{list_id}'

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "List #442 has been deleted.",
"data": [ ]
}

Remove Duplicate Contacts

Remove duplicate contacts

Parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	Your list id

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

put/v3/lists/{list_id}/remove-duplicates/

Request samples

application/json

{"fields": {"first_name": "first_name",
"last_name": "last_name"
}
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Your list duplicate contacts has been deleted.",
"data": {"deleted": 6
}
}

Import Contacts

Import contacts to list

Parameters

Parameter	In	Type	Required	Description
list_id	path	integer(int32)	true	Your contact list id you want to access.

Properties

Name	Type	Required	Restrictions	Description
file_url	string	true	none	URL of file to process
field_order	[string]	true	none	Order of fields in file

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

path Parameters

list_id

required

string

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/lists/{list_id}/import

Request samples

application/json

{"file_url": "{{fileURL}}",
"field_order": "test"
}

Response samples

200

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Your file is now queued.",
"data": {"msg": "Messages put on queue.",
"ids": ["6254358460638066203"
],
"id": "6254358460638066203"
}
}

View Contact Lists

Get list of searched contact list

Parameters

Parameter	In	Type	Required	Description
q	query	string	true	Your keyword or query.
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request

query Parameters

q	string Example: q=Test

Responses

200

Successful response

get/v3/search/contacts-lists

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/search/contacts-lists?q={q}'