API » REST Documentation

Copy2Contact REST API

REST is a simple and stateless method of calling a web service via standard HTTP requests that can be made with any browser. The advantage to REST is its simplicity and ease of testing. More info on REST can be found in the WikiPedia entry on REST.

Testing

Testing of REST requests to the Copy2Contact API can be done with any browser. In addition, a Firefox add-on called Poster is recommended to simplify testing. You may also find the Fiddler web debugging tool to be helpful.

Endpoint URL

The endpoint URL for Copy2Contact API REST requests is of the following format. Only the GET method is used.

https://api.copy2contact.com/rest/Type/MethodName?Params

Note that https (SSL) protocol must be used as insecure connections are not supported.

Type is either xml or json. This part of the URL determines the type of data returned. If type is json, the optional cbfn parameter may be given to specify a javascript callback function. Read more.

MethodName is one of the methods described below.

Params is a string of &-separated parameters to the method. Common parameters are described below.

Example:

https://api.copy2contact.com/rest/xml/ParseContact?text=John%20Smith%20cell:%20617.555.1212

Response Codes

REST methods return the standard HTTP response codes listed here. Some methods may return other response codes, which will be noted in that method's description.

200 OK - Success
403 Forbidden - AuthID or Password were incorrect. Detail is provided.
404 Method Not Supported - The method name specified in the URL is invalid.
426 HTTPS Is Required - HTTP transfers are not supported for security reasons.
500 Internal Server Error - An internal error occurred. Detail is usually provided and errors are logged.
503 Rate Limit Exceeded - The rate limit for this account has been exceeded. Detail is provided.
503 Month Limit Exceeded - The monthly hit limit for this account has been exceeded. Detail is provided.

Common Parameters

Most of the methods described take the following common parameters. Exceptions are noted in each method's description.

authid - Account AuthID [sign up]
pass - Account Password [sign up]
cbfn [optional] - Callback function name for json (ignored for xml). Read more.
xmltype [optional] - Set to text to return content type text/xml instead of application/xml (ignored for json). Read more.
emu [optional] - Set to basic, pro, comm, or ent to emulate rate limit settings of these account levels (developer accounts). Read more.

Character Encoding

All input text must be encoded using UTF-8. All output text is encoded in UTF-8.

Supported Methods

GetTypeScores

This method takes a string of text as its argument and returns two "scores" that assert the relative likelihood that the given text represents a contact or event. The scores can be compared to determine how to handle the text or whether it is relevant.

Parameters:

text [required] - The text to process

Returned Elements:

ContactScore - The relative score of the given text as a contact
EventScore - The relative score of the given text as an event

Example:

.../GetTypeScores?text=John%20Smith%20cell:%20617.555.1212

 

ParseEvent

This method takes a string of text as its argument and parses it into individual event fields.

Parameters:

text [required] - The text to process
localtime [required] - The local time at the user's location. Format "CCYYMMDDThhmmss", e.g. "20091215T122500"

overrideFrom [optional] - Set this to force the EventFrom element to the given value (developer accounts). Read more.
overrideTo [optional] - Set this to force the EventTo element to the given value (developer accounts). Read more.

Response Codes:

In addition to the standard response codes, this method may return the following:

400 Bad Request - localtime parameter format is incorrect.

Returned Elements:

EventNoTime - 0 or 1 indicating whether a time of day is associated with this event, e.g. "1"
EventDesc - The description of the event, e.g. "Staff meeting"
EventSubject - The "subject", if one appears in the text
EventLocation - The location of the event, if one appears in the text
EventLocationBare - The location with the preceeding keyword (e.g. "Where:") removed
EventFrom - The start time of the event. Format "CCYYMMDDThhmmss", e.g. "20091216T103000"
EventTo - The end time of the event. Format "CCYYMMDDThhmmss", e.g. "20091216T113000"

The following returned elements are based on the above and are provided for convenience:

EventFromYear - The year part of the EventFrom element, e.g. "2009"
EventFromMonth - The month part of the EventFrom element, e.g. "12"
EventFromDay - The day part of the EventFrom element, e.g. "16"
EventFromHour - The hour part of the EventFrom element, e.g. "10"
EventFromMinute - The minute part of the EventFrom element, e.g. "30"
EventFromSecond - The second part of the EventFrom element, e.g. "00"
EventToYear - The year part of the EventTo element, e.g. "2009"
EventToMonth - The month part of the EventTo element, e.g. "12"
EventToDay - The day part of the EventTo element, e.g. "16"
EventToHour - The hour part of the EventTo element, e.g. "11"
EventToMinute - The minute part of the EventTo element, e.g. "30"
EventToSecond - The second part of the EventTo element, e.g. "00"

Example:

.../ParseEvent?text=Staff%20meeting%20tomorrow%20at%2010:30&authid=00000&pass=xxxxx

 

ParseContact

This method takes a string of text as its argument and parses it into individual contact fields.

Parameters:

text [required] - The text to process

phone1Sources [optional] - Comma-separated list of source fields for ContactPhone1 convenience element. Read more.
phone2Sources [optional] - Comma-separated list of source fields for ContactPhone2 convenience element. Read more.
phone3Sources [optional] - Comma-separated list of source fields for ContactPhone3 convenience element. Read more.

lowercaseEmails [optional] - Set to 1 to format email addresses as all-lowercase
capitalizeAddresses [optional] - Set to 1 to auto-capitalize street address, city, state, and country
capitalizeStateAbbrevs [optional] - Set to 1 to make 2-letter state abbreviations all capitals
capitalizeNamesTitles [optional] - Set to 1 to auto-capitalize names and titles
capitalizeCos [optional] - Set to 1 to auto-capitalize the company name
allCapsCity [optional] - Set to 1 to make the city name all capitals
allCapsCountry [optional] - Set to 1 to make the country name all capitals
allCapsLastName [optional] - Set to 1 to make the contact's last name all capitals

stripLeadingPhone1s [optional] - Set to 1 to remove leading "1" from phone numbers
phoneNumberFormat [optional] - Set to one of the following to format phone numbers accordingly:

1 - no change
2 - remove all spaces only
3 - (212) 555-1212
4 - 212.555.1212
5 - 212-555-1212
6 - 212 555-1212

overrideEmail [optional] - Set this to force the ContactEmail element to the given value (developer accounts). Read more.
overrideName [optional] - Set this to force the ContactName element to the given value (developer accounts). Read more.
overrideFirst [optional] - Set this to force the ContactFirst element to the given value (developer accounts). Read more.

Returned Elements:

ContactPreNameTitle - Any title before the contact's name, e.g. "Mr.", "Mrs.", "Dr.", etc.
ContactName - The contact's last name, e.g. "Smith"
ContactFirst - The contact's first name, e.g. "John"
ContactMiddle - The contact's middle name, e.g. "Adam"
ContactPostNameTitles - Any title words after the contact's name, e.g. "Esq.", "M.D.", "Ph. D.", etc.

ContactTitle - The contact's job title, e.g. "Managing Editor"
ContactCompany - The contact's company name, e.g. "Acme Newspapers, Inc."

ContactAddress - The contact's street address, including multiple lines if present, e.g. "123 Main St. Suite 321"
ContactAddressSpaces - As above but with linebreaks converted to spaces
ContactAddressHtml - As above but with linebreaks converted to <br />

ContactCity - The contact's city, e.g. "Boston"
ContactState - The contact's state (if a US address), e.g. "Maine", "ME"
ContactZipCode - The contact's postal code, e.g. "02139", "TW11 8DH"
ContactCountry - The contact's country (if provided), e.g. "Canada"

ContactWork - The contact's complete office phone number, e.g. "617 555 1234 x. 23"
ContactWorkExt - The extension for the above number, e.g. "23"
ContactWorkNoExt - The above number without the extension part, e.g. "617 555 1234"
ContactHome - The contact's complete home phone number
ContactHomeExt - The extension for the above number
ContactHomeNoExt - The above number without the extension part
ContactFax - The contact's complete fax phone number
ContactFaxExt - The extension for the above number
ContactFaxNoExt - The above number without the extension part
ContactPager - The contact's complete pager phone number
ContactPagerExt - The extension for the above number
ContactPagerNoExt - The above number without the extension part
ContactMobile - The contact's complete mobile phone number
ContactMobileExt - The extension for the above number
ContactMobileNoExt - The above number without the extension part
ContactUnIdPhone1 - The first untagged number given for the contact
ContactUnIdPhone1Ext - The extension for the above number
ContactUnIdPhone1NoExt - The above number without the extension part
ContactUnIdPhone2 - The second untagged number given for the contact
ContactUnIdPhone2Ext - The extension for the above number
ContactUnIdPhone2NoExt - The above number without the extension part
ContactUnIdPhone3 - The third untagged number given for the contact
ContactUnIdPhone3Ext - The extension for the above number
ContactUnIdPhone3NoExt - The above number without the extension part

ContactEmail - The contact's email address, e.g. "email@company.com"
ContactEmail2 - Additional email address (if provided)
ContactEmail3 - Additional email address (if provided)
ContactEmail4 - Additional email address (if provided)

ContactURL1 - The contact's web URL, e.g. "www.company.com"
ContactURL2 - Additional web URL (if provided)
ContactURL3 - Additional web URL (if provided)
ContactURL4 - Additional web URL (if provided)

ContactIMName1 - The contact's instant messenger name, e.g. "funnyguy68"
ContactIMName2 - Additional instant messenger name (if provided)
ContactIMName3 - Additional instant messenger name (if provided)
ContactIMName4 - Additional instant messenger name (if provided)
ContactIMType1 - The instant messenger type for IMName1 (AIM, MSN, Yahoo, ICQ, IRC, Skype, GoogleTalk, Jabber, IM)
ContactIMType2 - The instant messenger type for IMName2 (AIM, MSN, Yahoo, ICQ, IRC, Skype, GoogleTalk, Jabber, IM)
ContactIMType3 - The instant messenger type for IMName3 (AIM, MSN, Yahoo, ICQ, IRC, Skype, GoogleTalk, Jabber, IM)
ContactIMType4 - The instant messenger type for IMName4 (AIM, MSN, Yahoo, ICQ, IRC, Skype, GoogleTalk, Jabber, IM)
ContactAIM - The contact's AIM ID
ContactMSN - The contact's MSN ID
ContactYahoo - The contact's Yahoo IM ID
ContactICQ - The contact's ICQ ID
ContactIRC - The contact's IRC ID
ContactSkype - The contact's Skype ID
ContactGoogleTalk - The contact's GoogleTalk ID
ContactJabber - The contact's Jabber ID

ContactLinkedIn - The contact's LinkedIn URL, e.g. "http://www.linkedin.com/in/myprofile"
ContactBlog - The contact's Blog URL, e.g. "http://www.company.com/blog/"
ContactTwitter - The contact's Twitter URL, e.g. "http://twitter.com/mytwittername"
ContactFacebook - The contact's Facebook URL, e.g. "http://www.facebook.com/myfacebookname"
ContactMySpace - The contact's MySpace URL, e.g. "http://www.myspace.com/myspacename"

ContactRemainingText - Any remaining text left over after parsing
ContactRemainingTextSpaces - As above but with linebreaks converted to spaces
ContactRemainingTextHtml - As above but with linebreaks converted to <br />

ContactAllText - All text provided to the ParseContact call
ContactAllTextSpaces - As above but with linebreaks converted to spaces
ContactAllTextHtml - As above but with linebreaks converted to <br />

The following returned elements are based on the above and are provided for convenience:

ContactAddress1 - The first line of the ContactAddress element if it contains more than one line. Read more.
ContactAddress2 - The second line of the ContactAddress element if it contains more than one line. Read more.
ContactAddress3 - The third line of the ContactAddress element if it contains more than one line. Read more.
ContactAddress4 - The fourth line of the ContactAddress element if it contains more than one line. Read more.

ContactFirstMiddleLast - The contact's first, middle, and last names together, separated by spaces, e.g. "John Adam Smith". Read more.
ContactFirstLast - The contact's first and last name together, separated by a space, e.g. "John Smith". Read more.
ContactFirstMiddle - The contact's first and middle name together, separated by a space, e.g. "John Adam". Read more.
ContactMiddleInitial - The contact's middle initial, if a middle name is present, e.g. "A". Read more.
ContactLastFirstMiddle - The contact's last name, first name, and middle name, e.g. "Smith, John Adam". Read more.
ContactLastFirst - The contact's last name, a comma, and first name, e.g. "Smith, John". Read more.

ContactPhone1 - A convenience element for forms with only a generic "Phone" field. Read more.
ContactPhone1Ext - The extension for the above number.
ContactPhone1NoExt - The above number without the extension part.
ContactPhone2 - A convenience element for forms with only a generic "Phone" field. Read more.
ContactPhone2Ext - The extension for the above number.
ContactPhone3NoExt - The above number without the extension part.
ContactPhone3 - A convenience element for forms with only a generic "Phone" field. Read more.
ContactPhone3Ext - The extension for the above number.
ContactPhone3NoExt - The above number without the extension part.

Example:

.../ParseContact?text=John%20Smith%20cell:%20617.555.1212&authid=00000&pass=xxxxx

 

GetMonthUsage

This method returns the number of hits to the API in the previous month for your AuthID. This can be useful for monitoring your quota usage.

Parameters:

None

Returned Elements:

Usage - The number of hits in the previous month

Example:

.../GetMonthUsage?authid=00000&pass=xxxxx

 

 

Newsletter
Signup