Can someone give me a simple example of how to upload a Contact image via the API? I am guessing it will involve a call to the File API as well but not sure.

I have the original image as a URL but want to store it in CiviCRM (not just reference the URL).

Bonus points for a nicely commented answer :)


1 Answer 1


Contact Image URL is directly stored in civicrm_contact table, so I think if you have the URL which can display an image, you should be directly able to use the contact create API as below -

$result = civicrm_api3('Contact', 'create', array(
  'contact_type' => "Individual",
  'first_name' => "first",
  'last_name' => "last",
  'image_URL' => "<url>",

If you're on version < 5.0, the contact summary page will render the image only iff the URL is in form of http://site-name/civicrm/contact/imagefile?photo=imageName.jpg and your image file should be present in your custom file upload directory.

There is now a patch(included in version 5.0) which allows the contact summary page to display any URL image irrespective of the photo param in the URL.

If you want to download a copy of a remote image to your local file system and use that, you could do something along the lines of:

$contactId = 123;
$imageName = 'jitendra.jpg';
$path = Civi::paths()->getPath(Civi::settings()->get('customFileUploadDir')) . $imageName;
file_put_contents($path, file_get_contents('https://i.sstatic.net/yjnic.jpg'));
civicrm_api3('Contact', 'create', [
  'id' => $contactId,
  'image_URL' => CRM_Utils_System::url('civicrm/contact/imagefile', ['photo' => $imageName], true)
  • thanks for the answer, Jitendra, very helpful. I still have one outstanding question though. How would I upload an image file so that it is available at site-name/civicrm/contact/imagefile?photo=imageName.jpg? Mar 21, 2018 at 11:03
  • Also, I played around with file uploading via the UI and the image URL was reported as http://chatbot.buildkit:8080/civicrm/file?reset=1&filename=michael_ed7e440cde7726911615c9e97042b177.png&mime-type=image/png. I was expecting something similar to http://site-name/civicrm/contact/imagefile... - any thoughts on that? Mar 21, 2018 at 11:10
  • May I know the CiviCRM version you are testing on? I guess contact upload uses that URL in the older versions. Mar 21, 2018 at 11:54
  • If you don't have the image file available in the custom upload directory - you can apply the PR mentioned in the answer and fed the URL to the image_url param in the API. Note the URL should be able to display an image. Mar 21, 2018 at 11:55
  • OK, I think I get it now. I have added an example to your answer to clarify my particular use case. Do you want to have a look and let me know what you think? Mar 21, 2018 at 15:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.