-
Notifications
You must be signed in to change notification settings - Fork 16
API
The keywords and JSON structure was inspired by https://jsonapi.org.
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.
- Original docs
- Creates a single contacts or updates the one which matches one of the identifiers.
- 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.
- Original docs
- Custom items will be created/updated depending if they has an
idor not.
The example payload bellow expects that there is some Custom Object called Products (with alias products) that has some Custom Fields (with aliases website, in-stock, multi, sku, color).
The format of the request and response payload is very similar.
A Custom Item must belong to a specific Custom Object so it would be clear what Custom Fields and permissions to apply to the Custom Item. The Custom Object can be identified by the id or alias.
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.
{
"email": "[email protected]",
"firstname": "John",
"customObjects": {
"data": [
{
"id": 1,
"alias": "products",
"data": [
{
"id": 23,
"name": "Hello From API2",
"attributes": {
"website": "https://mautic.org",
"in-stock": 45,
"multi": ["yellow", "blue"],
"sku": "2348720",
"color": "brown"
}
}
]
}
]
}
}
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.
The response payload adds the meta data into Custom Object and Custom Item parent element with limitations of the collections so it would be clear what the limit and ordering is. The collection limit, page and ordering is not configurable at the moment.
{
"email": "[email protected]",
"firstname": "John",
"customObjects": {
"data": [
{
"id": 1,
"alias": "products",
"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"
}
}
],
"meta": {
"page": {
"number": 1,
"size": 50,
},
"sort": "-dateAdded"
}
}
],
"meta": {
"page": {
"number": 1,
"size": 50,
},
"sort": "-dateAdded"
}
}
}
If Custom Object, Custom Item (if ID provided) or Custom Field provided in the request doesn't exist it will return HTTP status 400 (bad request) and no Contact nor Custom Item will be saved. The errors array in the response will contain details about what is wrong. Example:
{
"errors": [
{
"code": 400,
"message": "Custom Object with alias = invoice was not found",
"details": []
}
]
}