How to set a custom country field using the API

Question

Some fields that are stored as id references to other tables can be set by simply passing the value as an id, e.g. setting gender_id=Male works.

I have a custom fieldset attached to contacts that includes a country (of origin - it's different to of residence!) field, known affectionately as custom_77.

But I've noticed that the API doesn't like me to pass custom_77=Uganda - it complains that Uganda is not an integer. Can't fault it there :-)

My answer to the setting gender question provides a working solution: you can get it from getIdForLabel('contact', 'custom_77', 'Uganda'), or from any other country field, e.g. getIdForLabel('address', 'country_id', 'Uganda'), but as that turned out to be a very long winded solution when it was actually very simple, I thought I might, once again, be wrong! Hence this question.

Answer 1

Any field (including custom fields) that accepts an option value will take either its machine name or it's id. The machine names for countries are their ISO codes, e.g. the code for 'United States' is 'US'. So you could do:

civicrm_api3('Contact', 'create', array(
  'custom_77' => 'US',
));

which is equivalent to

civicrm_api3('Contact', 'create', array(
  'custom_77' => 1228,
));

The label "Uganda" will not work, as it's not considered reliable given translations and word-replacements.

To find the ISO code for a country, use the api explorer. Api Country get with name = Uganda reveals "iso_code": "UG"

Answer 2

Chain API call would be an answer for this. Let's for example :

$result = civicrm_api3('Country', 'get', array(
  'sequential' => 1,
   'name' => "India",
   'api.Contact.create' => array(
   'contact_id' => 202,
   'custom_7' => "\$value.id"),
));

So here we first fetching country on basis of its 'name' => "India" and providing your desired custom field(related to entity Contact) with its country.id (here "\$value.id")