Author Topic: API v3 - create/update contact+address+phone via REST interface (Read 1639 times)

davej · October 11, 2011, 10:09:28 am

Hi,

A developer who is trying to integrate Civi with an external system wants to submit a REST query containing contact details + multiple phone numbers & addresses and have this automatically create or update contact/phone/address records as needed. I.e. if the contact doesn't exist, create new contact + phone(s) + address(es); if the contact + home phone records exist but no work phone, then update the contact + home phone and create work phone.

He asks:

Quote

/sites/all/modules/civicrm/extern/rest.php?version=3&key=blah&api_key=blah&entity=Contact&action=get&contact_id=3885
only returns a single phone number.

Digging further in the explorer, I see that I can perform a query such as
/sites/all/modules/civicrm/extern/rest.php?version=3&key=blah&api_key=blah&entity=Phone&action=get&contact_id=3885
which will allow me to locate all phone numbers for a specific contact and thereby give me the ability to explicitly modify the correct one.

This does however make it look very much like I'm going to need to make multiple calls in order to perform a single update:
- if the person already exists (i.e. we have a CRM ID for them) retrieve their phone records. (1 call)
- for each phone number submitted, check to see if a phone number of that type already exists in that result set, if so, perform a call to update that specific phone number, alternatively, perform a call to create a new phone number of this type (at least 1, possibly 3 calls)
- check to see if the person has a mailing address (1 call)
- if so, update that with the new details, if not, then create a new address for them (1 call)
- update all other details for the person (1 call)

Overall, this begins to look like at least 7 calls, and it makes me think I must be missing something (else)…?

There was discussion at http://civicrm.org/API_version_3 about higher-level API functions handling this sort of thing. What's the best way to go about this currently?

Thanks,

Dave J

totten · October 11, 2011, 10:57:40 am

The "replace" operation _might_ help. The basic theory is that you can use one call to replace "the set of phone numbers belonging to the contact" with a new "set of phone numbers belonging to the contact" -- and it will automatically perform a series of searches, inserts, updates, and deletes. The "replace" operation is designed to work with chaining, so you can issue a "contact,create" or "contact,update" and then make chained calls to "api.email.replace" and "api.phone.replace". For example:

Code: [Select]

        civicrm_api('contact', 'update', array(
            'version' => 3,
            'id' => 123,
            'first_name' => 'Foo',
            'last_name' => 'Bar',
            'api.email.replace' => array(
                'values' => array(
                    array(
                        'email'            => 'foo@example.com',
                        'location_type_id' => 1,
                        'is_primary'       => 1,
                    ),
                    array(
                        'email'            => 'fbar@example.net',
                        'location_type_id' => 2,
                        'is_primary'       => 0,
                    ),
                ),
            ),
        )

This effectively changes the first and last names, adds the two given emails, and deletes any other unwanted emails. As a best-practice, one should include the 'id' of each email or phone record if you know it; doing so will lead to a SQL UPDATE instead of a combined SQL DELETE+SQL INSERT. Also, it's important to design/test carefully because this can unforgivingly delete data.

A series of examples are included under "testReplaceEmailsInChain" in http://svn.civicrm.org/civicrm/branches/v3.4/tests/phpunit/api/v3/EmailTest.php

I'm not sure how chaining works through the REST interface.

CiviCRM Community Forums (archive)

News:

Author Topic: API v3 - create/update contact+address+phone via REST interface (Read 1639 times)

davej

API v3 - create/update contact+address+phone via REST interface

totten

Re: API v3 - create/update contact+address+phone via REST interface