Difference between revisions of "CRM-2 Contacts API"

From Opentaps Wiki
Jump to navigationJump to search
Line 1: Line 1:
−
Contacts API is used to create and retreive contacts.
+
== Contacts API is used to create and retreive contacts. ==
  
 
The API calls follow the general RESTful pattern of [[CRM-2 API]].
 
The API calls follow the general RESTful pattern of [[CRM-2 API]].
Line 5: Line 5:
 
The base URL is <tt>http://crm-2-url/crm2/contact</tt>
 
The base URL is <tt>http://crm-2-url/crm2/contact</tt>
  
−
GET: Get a List of Contacts by:
+
=== GET: Get a List of Contacts ===
 
* contactId
 
* contactId
 
* emailAddress
 
* emailAddress
 
* attribute Map
 
* attribute Map
  
−
POST: Create or update Contact
+
=== 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 <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"}}}}
  
−
The following parameters are supported:
+
== 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
 
* firstName
 
* lastName
 
* lastName
Line 19: Line 52:
 
** 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 Map
+
* 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.

Revision as of 14:06, 11 April 2013

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 http://crm-2-url/crm2/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"}}}}

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}

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