Tutorial: Hello World

The API possibilities are vast and effective. To direct you on the right CRM integration path, we designed a sample application that creates a new lead named 'Tom Ford' and assigns it to a user with email 'bill@mail.com'.

At first, you need to set up some constants to deal with values that depend on who will be using this script. These values include:

• the user-specific API key,
• the key of the CRM in which the new lead will be created, and
• the email address of the user to whom it will be assigned.

Next step is to set up your HTTP connection. Note: the API only accepts secure connections via HTTPS.

Then, you can get down to building the request. The most important part is setting the Authorization header to provide the API key (find more details in the Authentication section below).

A top-level object with a single element named data is expected from all API POST and PUT requests. The successful responses will return a new ID. Besides, the data item should itself be an object that contains the parameters for the request. During a new lead creation these fields we want to set on the lead itself.

If the request was successful, you will get a response code of 201 notifying that the object was created. At the top level, this response will have a data field that stores the new lead ID.

If something went wrong during your request, you will receive a different status code, and the returned JSON will include the error field at the top level with a list of problems. You need to look at the first one and print out the message.

try {

   // the email of CRM user to which the Lead will be assigned 
   $userEmail = 'bill@mail.com';
   
   // new lead details
   $leadFirstName = 'Tom';
   $leadLastName = 'Ford';
  
   // search the user in CRM with a corresponding email
   $userApi = new \Data2CRMAPI\Resource\UserApi($client);
   $users = $userApi->fetchAll(50, 1, ['email.address' => $userEmail]);
  
   // the filters use Cache, so make sure that Cache is initialized; in case there is no cached data, Cache will be initialized automaticaly
   if (true === $userApi->getData()->isStatusDone()) {
       if (false === empty($users)) {
           // prepare the Lead data for recording
           $lead = new \Data2CRMAPI\Model\LeadEntity();
           $lead->setFirstName($leadFirstName);
           $lead->setLastName($leadLastName);
           $lead->setUser((new \Data2CRMAPI\Model\UserEntityRelation())->setId(current($users)->getId()));
          
           // create the Lead 
           $leadApi = new \Data2CRMAPI\Resource\LeadApi($client);
           $leadRelation = $leadApi->create($lead);
           echo 'Lead created: ' . $leadRelation->getId() . PHP_EOL;
       } else {
           // if there is no user with the specified email in the CRM, throw the error
           throw new \Exception('User with email "' . $userEmail . '" not found');
       }
   } else {
       // in case you couldn’t get cached data, show a corresponding message
       echo 'Status message: ' . $userApi->getData()->getStatusMessage() . PHP_EOL;
   }

} catch (\Data2CRMAPI\ApiException $exception) {
   // show the errors, if there were any
   echo 'Failed: #'
       . $exception->getCode()
       . ' => ' . $exception->getDetailCode() . ': ' . $exception->getDetailMessage()
       . ' => ' . print_r($exception->getDetailExtra(), true) . PHP_EOL
       . PHP_EOL;
} catch (\Exception $exception) {
   echo 'Failed: ' . $exception->getMessage() . PHP_EOL;
}