Contact PUT and company info

API Q&A
1

The behavior of contact PUT in the REST API with regards to company info is strange.

If either of the following are true…

  1. The Contact does not exist (i.e. the duplicate_option does not reveal a match)
  2. The Contact exists AND the Contact’s CompanyId field has a value.

… then a PUT will cause these results:

  • If company_name is provided but id is not, the info will be dropped.
  • If id is provided, then regardless of whether company_name is also provided, the Contact’s CompanyId field will be set to the supplied value and the Contact’s Company field will be set to the value taken from the Company record corresponding to id.

If either of these situations are true…

  • The Contact exists AND its CompanyId field does NOT have a value AND the Contact’s Company field has a value.
  • The Contact exists AND its CompanyId field does NOT have a value AND the Contact’s Company field is empty.

… then a PUT will cause these results:

  • If only company_name is provided, it will be dropped.
  • If id is provided, then regardless of whether company_name is also provided, the Contact’s Company field will be set but the Contact’s CompanyId field will not.

I would expect that if a valid company id is supplied then the Contact’s CompanyId would be set to the supplied value – so I consider the second set of behaviors to be a bug.

From my point of view, the most desirable behavior would actually be something different, yet consistent across all create/update scenarios:

  • If the id field is provided and corresponds to a valid Company record, then regardless of the supplied value for company_name, set the Contact’s CompanyId field to the supplied value and the Company field to the value extracted from the Company record corresponding to id.
  • If only company_name is provided, then zero out the Contact’s CompanyId field and set the Contact’s Company field to the supplied value.

That would greatly simplify using PUT to create a create or update a contact. Right now, in order not to lose Company information, I have to perform two additional API calls to the legacy XML RPC API in order to find or create a Company record ID before I can PUT a Contact.

I argue that this requested behavior is RESTFUL because in no circumstances does it cause the side effect of creating a Company record – only the values of the Contact record are affected.

(Edit: use the correct names for the Contact record fields according to the Table Schema Docs).

2

Hey @Marvin_Humphrey, first I would like to say thank you for the formatting in this well written post. I have been asked about this behavior a few times recently… I know there was quite a bit of research done initially and the outcome was to use the linked company field. Can you submit this as a support case here? This will document the issue and allow the team to work on it.

Thank you,
Carlos