Skip to content

API

Jump to bottom
John Linhart edited this page Jun 11, 2019 · 14 revisions

Create/Update custom items together with contact

The Custom Object plugin listens on some contact API endpoints request and if the payload contains custom items it will save those and link them to the contact.

Supported routes

POST api/contacts/new

  • Original docs
  • Creates a single contacts or updates the one which matches one of the identifiers.

POST api/contacts/batch/new

  • Creates a multiple contacts or updates the one which matches one of the identifiers. The only difference between the single and the batch request is that the batch sends an array of contacts over a single contact.

PATCH api/contacts/[contact_id]/edit

  • Original docs
  • Updates a contact with the values from the request. Leaves the rest untouched. Custom items will be created/updated depending if they has an id or not.

PUT api/contacts/[contact_id]/edit

  • Original docs
  • Updates a contact with the values from the request. Clears all the values that were not in the request. Custom items will be created/updated depending if they has an id or not.

Example payload:

The example payload bellow expects that there is some Custom Object called Products (with alias products) that has some Custom Fields.

If you wish to insert a Custom Item then do not send its id. However, if you wish to update a Custom Item then you must provide the ID.

Mautic will firstly validate all the Custom Objects, Custom Items and Custom Fields. Then it will validate the contact itself. If all validations passes it will save the contact, save the Custom Items together with Custom Field values and then it will link all the custom items to the contact.

The format of payload bellow can be used in the request and same format will be sent in the response. The response will contain the custom objects, items and field values only if includeCustomObjects=true query parameter is added to avoid slowing down requests where custom objects aren't necessary. Example: POST api/contacts/new?includeCustomObjects=true.

{
    "email": "john@doe.email",
    "firstname": "John",
    "customObjects": {
        "products": {
            "id": 1,
            "data": [
                {
                    "id": 23,
                    "name": "Hello From API2",
                    "language": null,
                    "category": null,
                    "isPublished": true,
                    "dateAdded": "2019-06-07T11:52:01+00:00",
                    "dateModified": "2019-06-07T11:52:01+00:00",
                    "createdBy": 1,
                    "modifiedBy": 1,
                    "attributes": {
                        "website": "https://mautic.org",
                        "in-stock": 45,
                        "multi": ["yellow", "blue"],
                        "sku": "2348720",
                        "color": "brown"
                    }
                }
            ]
        }
    }
}

Errors

If Custom Object, Custom Item (if ID provided) or Custom Field provided in the request doesn't exist it will return HTTP status 404 and no Contact nor Custom Item will be saved.

Clone this wiki locally