CREATE CONTACT LIST

Create a new contact list and add to account

This operation adds a contact list to your account using one of four inputs: list of contacts, numbers string, list of contactIds, or a CSV file containing contacts or numbers. If more than one ContactSource is specified, it only takes into account one source based on the order listed above.

When importing contact lists, the system performs several processes to check the accuracy of the list. For example, our system checks whether a number is formatted correctly, is invalid, is duplicated in another contact list, or is on your Do Not Contact list. The API calls have their default validation error resolutions set differently than the defaults set on the CallFire web site under Settings | List Validation. The API validation defaults are:

Status Resolution
COLUMNS_UNMAPPED Resolution USE_DEFAULT_COLUMNS
LIST_HAS_DUPLICATE_NUMBERS Resolution SCRUB
LIST_HAS_DNC_CONTACTS Resolution SCRUB
LIST_HAS_CONTACT_CONFLICTS Resolution MERGE
LIST_HAS_INVALID_NUMBERS Resolution SCRUB

REQUEST PARAMETERS

Parameter Data Type Demo Value Description
CreateContactList object Create ContactList using attached info
RequestId anyURI MyUniqueIdForThisRequest Unique ID, used to de-dup requests and make sure request is not processed twice
Name string My College Friends Name of contact list
Validate boolean false Turn off list validation (default: true)
ContactSource object List of contacts, numbers, contactIds, or csv file.
Contact * object Info about the people you want to contact. Any info needed can be stored under Contact as an extra attribute.
lastName string Doe Last name
externalId string nb-1010 id of contact defined by external system (NATION_BUILDER, GOOGLE_GROUPS, etc...)
mobilePhone PhoneNumber 18185551414 E.164 11 digit number
firstName string John First name
externalSystem string NATION_BUILDER System where externalId was generated from (NATION_BUILDER, GOOGLE_GROUPS, etc...)
homePhone PhoneNumber 18185551212 E.164 11 digit number
workPhone PhoneNumber 18185551313 E.164 11 digit number
zipcode string 98154 5 digit zipcode
Id long 123 Unique ID of Contact
ContactId * List[long] List of existing contact ids
File * base64Binary Csv file attachment containing list of contacts or numbers
Numbers * object List of E.164 11 digit numbers space or comma seperated and optional fieldName
fieldName string field number should be assigned to homePhone, workPhone or mobilePhone (default: homePhone)

RESPONSE PARAMETERS

Parameter Data Type Description
CreatedId long Unique ID of resource

EXAMPLE: Create a new Contact List with existing Contacts

In this example we are creating a new contact list with contacts identified by "263582943003" , "263582944003", "263582945003".

using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {
        public string CreateContactList()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            RestRequest("contact/list", Method.POST);
            request.AddParameter("RequestId", '12345678909');
            request.AddParameter("Name", "ExampleList");
            request.AddParameter("ContactId", "263582943003,263582944003,263582945003");

            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

Response Parameters

The contact list was successfully created

Response Code: 201

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:Id>323737003</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/contact/list/323737003</r:Location>

</r:ResourceReference>

EXAMPLE: Create a new Contact List while creating new Contacts

In this example we are creating a new contact list with a new contact named "John Doe"

using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {
        public string CreateContactList()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            RestRequest("contact/list", Method.POST);
            request.AddParameter("Contact[0][firstName]", "John");
            request.AddParameter("Contact[0][lastName]", "Doe");
            request.AddParameter("Contact[0][zipcode]", "12345");
            request.AddParameter("Contact[0][homePhone]", "12345678909");
            request.AddParameter("Contact[0][workPhone]", "12345678909");
            request.AddParameter("Contact[0][mobilePhone]", "12345678909");
            request.AddParameter("Contact[0][externalId]", "ABC1234");
            request.AddParameter("Contact[0][externalSystem]", "ExternalSystem");

            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

If you try to set ContactId to add existing contacts and to create contacts at the same time, only the last ones will get added to the new list. We suggest to do this as a second step in your process using AddContactsToList and add existing contacts there.

Response Parameters

The contact list was successfully created

Response Code: 201

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

   <r:Id>323755003</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/contact/list/323755003</r:Location>

</r:ResourceReference>

No contacts provided

Response code: 400

If you don't provide any contacts nor create new ones, you will receive response code 400 and the following XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:HttpStatus>400</r:HttpStatus>

    <r:Message>No contacts provided</r:Message>

</r:ResourceException>

You cannot create an empty contact list.