While going over Mautic’s REST API documentation to learn how to edit contacts, I had faced a question.
Given that the a contact’s ID field is internal to mautic (it’s set automatically when creating a contact and not related to any other 3rd party ID field), how can one know what is the ID of the contact he would like to edit?
As I expect that the unique property of contacts is the email field, how can I edit a contact via the API using the email as an identifier?
I did a little research and found that if I call the /create/ with an existing email address, it will modify the existing contact with the given email. As this is not very intuitive (and not documented), I was wondering if this is the correct way of doing things.
Sorry if the solution is trivial and I haven’t figured it out, but mostly an internal ID field isn’t being used as an identifier for an external API usage.
Thanks in advance.
Update:
So the two ways I found in order to achieve that are:
Calling /contacts/new with an existing email address, which will modify the contact
Calling /contacts with where clause, which has a horrific syntax (see an example below).
Am I missing a different, better, way of editing a contact? This should be so intuitive to do!
Where clause example: https://your.mautic.url/api/contacts?where[0][col]=email&where[0][expr]=equals&where[0][val]=whyisithard@example.com
@crispyholiday I was just looking at this exact same thing, editing a contact via the API and I was going to get the ID from the cookie, mtc_id, however, it turns out that the /contact/ID/edit functionality doesn’t appear to work at all, at least not as documented.
PATCH requests return 200 response with nothing changed and PUT requests return 200 response and delete all details on the contact!!!
So, the /contact/new with the email address appears to be the best way to go and actually works better for me and my use case as I was looking to see if a contact existed and then edit it if it did or create it if it didn’t (the functionality PUT should provide), so thanks for pointing out that it worked like that.
I’m a bit late here but wanted to say thanks for the tips and share what worked for me. We ran into a similar use case where we needed to look up the contact ID and then patch the contact record (including the option to change the user’s email address).
As @crispyholiday mentioned, the syntax is ugly but calling /contact with a where clauses seems to work fine in Mautic 4… in case it helps others, here’s an example:
GET https://your.mautic.url/api/contacts?where%5B0%5D%5Bcol%5D=email&where%5B0%5D%5Bexpr%5D=eq&where%5B0%5D%5Bval%5D=email%40mautic.org
The brackets are encoded. If you’re working in Javascript, then you’ll need to encode that last email parameter (example: encodeURIComponent("email@mautic.org")).
The PATCH operation to modify a contact (/api/contacts/<ID>/edit) appears to be working if the Content-Type header is set to application/json and you include a body of raw JSON changes such as {"firstname":"New","email":"new@mautic.org"}.
@thmclellan thanks so much for coming back to post your findings!
It may interest you to know we are totally re-writing the dev docs and we are not far off being ready to launch, just a few more sections that need pulling over and updating.
Any help with this would be hugely appreciated if folks would like to get better acquainted with Mautic under the hood while reviewing and updating the docs!
Thanks @rcheesley! Nice to see the new docs. I see you got my basic PR to add this example, awesome!
I’m new to Mautic and it’s been a great experience so far… incredible value and it seems like a mature and well thought out product. Thanks for making it such a welcoming community!
Yes - thanks so much for taking the time to make the PR!
Great to hear that you’ve had a positive experience so far, we’re always open to feedback to make it better!
If you have any spare time on a Friday do join us for our Open Source Friday community sprints where we collectively work on testing bugs/features, writing docs and whatever else is on the table!
From the dev side of things we mostly work in #t-product on Slack (Slack if you aren’t there yet) but I post a pinned thread on the forums each week as well with links to what we are prioritising.
