Contacts

Create List

Lists

Everything about creating and manipulating contact lists

Servers

https://rest.clicksend.com/

View List Contacts

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here's your list of contacts."

dataArray of objects(contact)

Example: [{"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"}]

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here's your list of contacts.",
  "data": [
    { … },
    { … }
  ]
}

Create New Contact

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

phone_numberstring

Example: "3724763278"

first_namestring

Example: "test"

last_namestring

Example: "test"

custom_1string

Example: "t"

custom_2string

Example: "e"

custom_3string

Example: "s"

custom_4string

Example: "t"

date_addedstring or null

fax_numberstring or null

organization_namestring or null

emailstring or null

address_line_1string or null

Example: "x"

address_line_2string or null

address_citystring or null

address_statestring or null

address_postal_codestring or null

address_countrystring or null

Example: "AU"

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \

     --data-binary "    {
        \"phone_number\":\"+16783270696\",
        \"first_name\":\"Ellen\",
        \"last_name\":\"Diaz\",
        \"custom_1\":\"Custom 1\",
        \"custom_2\":\"Custom 2\",
        \"custom_3\":\"Custom 3\",
        \"custom_4\":\"Custom 4\",
        \"fax_number\":\"+16783270696\",
        \"organization_name\":\"Awesome Organization\",
        \"email\":\"ellen@diaz.com\",
        \"address_line_1\":\"Block 2\",
        \"address_line_2\":\"Cool Bldg.\",
        \"address_city\":\"Nevada\",
        \"address_state\":\"Las Vegas\",
        \"address_postal_code\":\"36063\",
        \"address_country\":\"US\"
    }" \
'https://rest.clicksend.com/v3/lists/{list_id}/contacts'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here's your list of contacts."

dataobject(contact)

Response

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

Request

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

Path

from_list_idstringrequired

contact_idstringrequired

to_list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

object

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \
'https://rest.clicksend.com/v3/lists/{from_list_id}/contacts/{contact_id}/copy/{to_list_id}'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Contact #1 has been copied to List #429"

dataobject(contact)

Response

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

Request

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

Path

from_list_idstringrequired

contact_idstringrequired

to_list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

object

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \
'https://rest.clicksend.com/v3/lists/{from_list_id}/contacts/{contact_id}/transfer/{to_list_id}'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Contact #1 has been transferred to List #429"

dataobject(contact)

Response

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

Request

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

Path

list_idstringrequired

opt_out_list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

object

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

'https://rest.clicksend.com/v3/lists/{list_id}/remove-opted-out-contacts/{opt_out_list_id}'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Optout contacts has been deleted."

dataobject

Response

application/json

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

View Lists

Request

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

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here are your data."

dataobject

Response

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": [ … ]
  }
}

Create List

Request

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

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

list_namestring

Example: "test"

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \

     --data-binary "    {
        \"list_name\":\"ListCT3QrVL4od\"
    }" \
'https://rest.clicksend.com/v3/lists'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "New list has been created."

dataobject(contact_list)

Response

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

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Here are your data."

dataobject(contact_list)

Response

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

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

list_namestring

Example: "test"

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \
     --header "Content-Type: application/json" \

     --data-binary "    {
        \"list_name\":\"ListlPJf33ksjP\"
    }" \
'https://rest.clicksend.com/v3/lists/{list_id}'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "List #439 has been updated."

dataobject(contact_list)

Response

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

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

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

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

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "List #442 has been deleted."

dataArray of items

Example: []

Response

application/json

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

Remove Duplicate Contacts

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

fieldsobject

Example: {"first_name":"first_name","last_name":"last_name"}

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

     --header "Content-Type: application/json" \
     --data-binary "{
    \"fields\":[
        \"phone_number\",
        \"first_name\",
        \"last_name\",
        \"fax_number\",
        \"address_country\"
    ]
}" \
'https://rest.clicksend.com/v3/lists/{list_id}/remove-duplicates'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Your list duplicate contacts has been deleted."

dataobject

Response

application/json

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

Import Contacts

Request

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

Path

list_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

file_urlstring

Example: "{{fileURL}}"

field_orderstring

Example: "test"

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

     --header "Content-Type: application/json" \
     --data-binary "{
    \"file_url\":\"http://yourdomain.com/import.csv\",
    \"field_order\":[
        \"phone\",
        \"first_name\",
        \"last_name\",
        \"custom1\",
        \"custom2\",
        \"custom3\",
        \"custom4\",
        \"fax_number\",
        \"organization_name\",
        \"email\",
        \"address_line_1\",
        \"address_line_2\",
        \"address_city\",
        \"address_state\",
        \"address_postal_code\",
        \"address_country\"
    ]
}" \
'https://rest.clicksend.com/v3/lists/{list_id}/import'

Responses

Successful response

Bodyapplication/json

http_codeinteger

The HTTP status code of the response.

Example: 200

response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Your file is now queued."

dataobject

Response

application/json

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

View Contact Lists

Request

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

Query

qstring

Example: q=Test

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

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

Responses

Successful response

Bodyapplication/json

Response

application/json

null

Lists

View List Contacts

Request

parameters

Responses

Was this helpful?

Create New Contact

Request

parameters

Properties

Responses

Was this helpful?

Copy Contact to List

Request

Parameters

Responses

Was this helpful?

Transfer Contact to List

Request

Parameters

Responses

Was this helpful?

Remove Opted Out Contacts

Request

Parameters

Responses

Was this helpful?

View Lists

Request

Parameters

Responses

Was this helpful?

Create List

Request

Parameters

Responses

Was this helpful?

View Secific List

Request

Parameters

Responses

Was this helpful?

Update List

Request

Parameters

Responses

Was this helpful?

Delete List

Request

Parameters

Responses

Was this helpful?

Remove Duplicate Contacts

RequestExpand all

Parameters

Responses

Was this helpful?

Import Contacts

Request

Parameters

Properties

Responses

Was this helpful?

View Contact Lists

Request

Parameters

Responses

Was this helpful?

Request