Difference between revisions of "CRM-2 Contacts API"

From Opentaps Wiki
Jump to navigationJump to search
(New page: Contacts API is used to create and retreive contacts. The API calls follow the general RESTful pattern of CRM-2 API. The base URL is <tt>http://crm-2-url/crm2/contact</tt> , only POS...)
 
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
Contacts API is used to create and retreive contacts.
+
== Contacts API ==
 +
 
 +
A Contact is a person or a company, similar to the contacts in your iPhone/Android address book.  It may have name, company name, and multiple points of contact, including emails, phone numbers, user logins, twitter, facebook, etc. per contact. It may also be associated with one or more User entities for accessing the system.  Each Contact is associated with a clientDomain.
  
 
The API calls follow the general RESTful pattern of [[CRM-2 API]].
 
The API calls follow the general RESTful pattern of [[CRM-2 API]].
  
−
The base URL is <tt>http://crm-2-url/crm2/contact</tt> , only POST is currently supported, which is used to create or update a contact.
+
The base URL is <tt>https://crm2.opentaps.com/contact</tt>
  
 +
=== GET: Get a List of Contacts ===
 +
* contactId
 +
* emailAddress
 +
* attribute Map
  
−
The following parameters are supported:
+
=== POST: Create a contact ===
 
* firstName
 
* firstName
 
* lastName
 
* lastName
Line 13: Line 19:
 
** emailN (the email address)
 
** emailN (the email address)
 
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
 
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
−
* attribute_XXX (can define additional attributes where XXX is the attribute name)
+
* attribute Map (described as a series of <tt>attribute_${key}=${value}</tt> parameters)
 +
 
 +
The operation returns a JSON response with the created contact eg:
 +
  {"result":{"resultValue":{"contactId":"5166b967e4b0f6e6cd09e653","firstName":"test","clientDomain":"mydomain.com","emails":[{"email":"test@example.com","purpose":"PRIMARY"}],"attributes":{"somekey":"somevalue"}}}}
 +
 
 +
=== PUT: Update a contact ===
 +
* firstName
 +
* lastName
 +
* companyName
 +
* emailsNumber (used to iterate the following parameter where N is an index number)
 +
** emailN (the email address)
 +
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
 +
* attribute Map (described as a series of <tt>attribute_${key}=${value}</tt> parameters)
 +
 
 +
Note that when updating:
 +
* the attributes are always overwritten so not gving any attribute will remove the existing ones
 +
* emails are only overwritten if at least one email is given or emailsNumber is set to 0 in which case the existing ones will be removed
 +
* firstName, lastName, companyName are only updated when given, they must be given and set to an empty value to be removed
 +
 
 +
The operation returns a JSON response with the new values of the updated contact eg:
 +
  {"result":{"resultValue":{"contactId":"5166b967e4b0f6e6cd09e653","firstName":"test","clientDomain":"mydomain.com","emails":[{"email":"test@example.com","purpose":"PRIMARY"}],"attributes":{"somekey":"somevalue"}}}}
 +
 
 +
=== DELETE: Delete a Contact ===
 +
* contactid
 +
 
 +
Deletes the referenced contact and removes all activities associated with the Contact.
 +
 
 +
== Import Contact API ==
 +
 
 +
A similar API is available to easily import contacts, it only allows POST operations but will create the contacts or update if one is found matching the given attributes.
  
 +
The base URL is <tt>http://crm-2-url/crm2/contact-import</tt>
 +
 +
=== POST: Create or update Contact ===
 +
* firstName
 +
* lastName
 +
* companyName
 +
* emailsNumber (used to iterate the following parameter where N is an index number)
 +
** emailN (the email address)
 +
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
 +
* attribute Map (described as a series of <tt>attribute_${key}=${value}</tt> parameters)
  
 
Only the attributes given as attribute_XXX are used to find an existing contact for update, if they are not given and / or a contact matching those is not found the operation will create a new contact.
 
Only the attributes given as attribute_XXX are used to find an existing contact for update, if they are not given and / or a contact matching those is not found the operation will create a new contact.
Line 20: Line 65:
 
The operation returns a JSON response with the contact ID of the created or updated record, eg:
 
The operation returns a JSON response with the contact ID of the created or updated record, eg:
 
   { "contact": { "contactId": XXX } }
 
   { "contact": { "contactId": XXX } }
 +
 +
The attribute Map is described as a series of <tt>attribute_${key}=${value}</tt> parameters.  For example, attribute_opentapsPartyId=12345 will become {opentapsPartyId:12345}
 +
 +
== Contact Group API ==
 +
 +
Contact Groups are groups of Contacts.  For example, you may have a Group called "Company X" for everybody who works at Company X or "Friends" for your personal friends.
 +
 +
A Contact Group has a group name and a list of contacts. 
 +
 +
The base URL is <tt>https://crm2.opentaps.com/contact-group</tt>  The API available are:
 +
 +
=== POST: Create a Contact Group ===
 +
 +
* groupName
 +
* clientDomain
 +
 +
Requires CONTACT_UPDATE security
 +
 +
=== PUT: Update a Contact Group ===
 +
 +
* groupName
 +
* clientDomain
 +
 +
Requires CONTACT_UPDATE security
 +
 +
=== GET: Get Contact Groups ===
 +
 +
* groupName - optional.  If specified, returns groups which contain the group name, case-insensitive.  "FRIENDS" and "friends" both will return all groups which contain these words.
 +
* clientDomain
 +
 +
Requires CONTACT_VIEW security
 +
 +
=== DELETE: Delete Contact Group ===
 +
 +
* groupId -- You must specify the unique ID of the contact group to delete it.
 +
* clientDomain
 +
 +
Requires CONTACT_UPDATE security
 +
 +
== Contact Group Member API ==
 +
 +
You can use this API to add or remove members from a Contact Group, or find Contact Groups from its members or find the members of a Contact Group.
 +
 +
The base URL is <tt>https://crm2.opentaps.com/contact-group-member</tt>.  The API available are:
 +
 +
=== POST: Add a Member to a Contact Group ===
 +
 +
* groupId - groupId is the unique ID of your Contact Group
 +
* contactId - contactId is the unique ID of your Contact. 
 +
* clientDomain
 +
 +
Requires CONTACT_UPDATE security
 +
 +
=== DELETE: Delete a Member from a Contact Group ===
 +
 +
* groupId
 +
* contactId
 +
* clientDomain
 +
 +
Requires CONTACT_UPDATE security
 +
 +
=== GET: Find Contacts of a Group or Find Groups of a Contact ===
 +
 +
* groupId - if specified, returns List of all the Contacts of this Group (not contactIds but actual Contacts)
 +
* contactId - if groupId is not specified, then returns List of all Contact Groups which contain the contactId
 +
* clientDomain
 +
 +
Requires CONTACT_VIEW security

Latest revision as of 00:02, 25 January 2014

Contacts API

A Contact is a person or a company, similar to the contacts in your iPhone/Android address book. It may have name, company name, and multiple points of contact, including emails, phone numbers, user logins, twitter, facebook, etc. per contact. It may also be associated with one or more User entities for accessing the system. Each Contact is associated with a clientDomain.

The API calls follow the general RESTful pattern of CRM-2 API.

The base URL is https://crm2.opentaps.com/contact

GET: Get a List of Contacts

  • contactId
  • emailAddress
  • attribute Map

POST: Create a contact

  • firstName
  • lastName
  • companyName
  • emailsNumber (used to iterate the following parameter where N is an index number)
    • emailN (the email address)
    • emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
  • attribute Map (described as a series of attribute_${key}=${value} parameters)

The operation returns a JSON response with the created contact eg: 

 {"result":{"resultValue":{"contactId":"5166b967e4b0f6e6cd09e653","firstName":"test","clientDomain":"mydomain.com","emails":[{"email":"test@example.com","purpose":"PRIMARY"}],"attributes":{"somekey":"somevalue"}}}}

PUT: Update a contact

  • firstName
  • lastName
  • companyName
  • emailsNumber (used to iterate the following parameter where N is an index number)
    • emailN (the email address)
    • emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
  • attribute Map (described as a series of attribute_${key}=${value} parameters)

Note that when updating:

  • the attributes are always overwritten so not gving any attribute will remove the existing ones
  • emails are only overwritten if at least one email is given or emailsNumber is set to 0 in which case the existing ones will be removed
  • firstName, lastName, companyName are only updated when given, they must be given and set to an empty value to be removed

The operation returns a JSON response with the new values of the updated contact eg: 

 {"result":{"resultValue":{"contactId":"5166b967e4b0f6e6cd09e653","firstName":"test","clientDomain":"mydomain.com","emails":[{"email":"test@example.com","purpose":"PRIMARY"}],"attributes":{"somekey":"somevalue"}}}}

DELETE: Delete a Contact

  • contactid

Deletes the referenced contact and removes all activities associated with the Contact.

Import Contact API

A similar API is available to easily import contacts, it only allows POST operations but will create the contacts or update if one is found matching the given attributes.

The base URL is http://crm-2-url/crm2/contact-import

POST: Create or update Contact

  • firstName
  • lastName
  • companyName
  • emailsNumber (used to iterate the following parameter where N is an index number)
    • emailN (the email address)
    • emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
  • attribute Map (described as a series of attribute_${key}=${value} parameters)

Only the attributes given as attribute_XXX are used to find an existing contact for update, if they are not given and / or a contact matching those is not found the operation will create a new contact.

The operation returns a JSON response with the contact ID of the created or updated record, eg: 

 { "contact": { "contactId": XXX } }

The attribute Map is described as a series of attribute_${key}=${value} parameters. For example, attribute_opentapsPartyId=12345 will become {opentapsPartyId:12345}

Contact Group API

Contact Groups are groups of Contacts. For example, you may have a Group called "Company X" for everybody who works at Company X or "Friends" for your personal friends.

A Contact Group has a group name and a list of contacts.

The base URL is https://crm2.opentaps.com/contact-group The API available are:

POST: Create a Contact Group

  • groupName
  • clientDomain

Requires CONTACT_UPDATE security

PUT: Update a Contact Group

  • groupName
  • clientDomain

Requires CONTACT_UPDATE security

GET: Get Contact Groups

  • groupName - optional. If specified, returns groups which contain the group name, case-insensitive. "FRIENDS" and "friends" both will return all groups which contain these words.
  • clientDomain

Requires CONTACT_VIEW security

DELETE: Delete Contact Group

  • groupId -- You must specify the unique ID of the contact group to delete it.
  • clientDomain

Requires CONTACT_UPDATE security

Contact Group Member API

You can use this API to add or remove members from a Contact Group, or find Contact Groups from its members or find the members of a Contact Group.

The base URL is https://crm2.opentaps.com/contact-group-member. The API available are:

POST: Add a Member to a Contact Group

  • groupId - groupId is the unique ID of your Contact Group
  • contactId - contactId is the unique ID of your Contact.
  • clientDomain

Requires CONTACT_UPDATE security

DELETE: Delete a Member from a Contact Group

  • groupId
  • contactId
  • clientDomain

Requires CONTACT_UPDATE security

GET: Find Contacts of a Group or Find Groups of a Contact

  • groupId - if specified, returns List of all the Contacts of this Group (not contactIds but actual Contacts)
  • contactId - if groupId is not specified, then returns List of all Contact Groups which contain the contactId
  • clientDomain

Requires CONTACT_VIEW security

Retrieved from "https://docs.opentaps.org/docs/index.php?title=CRM-2_Contacts_API&oldid=7441"