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
|