Put and Post JSON (putJSON and postJSON methods) – Cordial Knowledge Base

How can we help?

Overview

The data stored within an externally-hosted server can be retrieved or updated by making a post/putJSON request to an API endpoint.

In this article, you'll find two examples of posting contact data to an external API. One possible use case is sending contact information to a customer service or loyalty application.

We'll describe the putJSON method in this article. The postJSON method can be used in a similar manner. The selection of the method and parameter settings depends on the implementation of the post and put methods on the external server.

First example

Use the tabs below to view the Smarty script and the rendered output received as a result. For rendered output, the result of the request can be reviewed with the jsonPrettyPrint($data) method.

Copy and paste the code below into a message content or data job transformation script and preview the results. You can also send the message or run the data job to examine external data changes.

{$result = $utils->postJson('https://postman-echo.com/post', [
    "firstName" => 'John',
    "lastName" => 'Smith',
    'email' => 'jsmith@gmail.com',
    'id' => 101],
    ['headers'=>['Authorization' => 'Basic Y29yZGlhbF9zYXlzOmhlbGxv'],
    'timeout' => 6, "cacheMinutes" => 10])}
    {$utils->jsonPrettyPrint($result)}

[
    {
        "statusCode": 200,
        "headers": {
            "Date": [
                "Tue, 26 Apr 2022 12:22:35 GMT"
            ],
            "Content-Type": [
                "application\/json; charset=utf-8"
            ],
            "Content-Length": [
                "525"
            ],
            "Connection": [
                "keep-alive"
            ],
            "ETag": [
                "W\/\"20d-+gcDrs5d958cxHuybRpToiFbjew\""
            ],
            "Vary": [
                "Accept-Encoding"
            ],
            "set-cookie": [
                "sails.sid=s%3AI1ab0jhxbf6Hgt-elkujWi01RPVGKUC7.giirYI%2BWP2N9635pAbOIad0AbWLmCBwIERRe6eIYM80; Path=\/; HttpOnly"
            ]
        },
        "data": {
            "args": [],
            "data": {
                "firstName": "John",
                "lastName": "Smith",
                "email": "jsmith@gmail.com",
                "id": 101
            },
            "files": [],
            "form": [],
            "headers": {
                "x-forwarded-proto": "https",
                "x-forwarded-port": "443",
                "host": "postman-echo.com",
                "x-amzn-trace-id": "Root=1-6267e40b-4acf40691c406ac61c60214e",
                "content-length": "75",
                "authorization": "Basic Y29yZGlhbF9zYXlzOmhlbGxv",
                "content-type": "application\/json",
                "user-agent": "Cordial Platform"
            },
            "json": {
                "firstName": "John",
                "lastName": "Smith",
                "email": "jsmith@gmail.com",
                "id": 101
            },
            "url": "https:\/\/postman-echo.com\/post"
        },
        "error": null
    }
]

Second example

The following example uses the method to make a POST/PUT request to an API endpoint. For rendered output, the result of the request can be reviewed with the jsonPrettyPrint($data) method.

The system variable $contact available in the message and data job context is used in this example.

{$result = $utils->postJson('https://postman-echo.com/post',
  $contact,
  ['headers'=>['Authorization' => 'Basic Y29yZGlhbF9zYXlzOmhlbGxv'],
   'timeout' => 6, 'cacheMinutes' => 10])}
  {$utils->jsonPrettyPrint($result)}

{
    "statusCode": 200,
    "headers": {
        "Date": [
            "Tue, 26 Apr 2022 12:35:43 GMT"
        ],
        "Content-Type": [
            "application\/json; charset=utf-8"
        ],
        "Content-Length": [
            "1250"
        ],
        "Connection": [
            "keep-alive"
        ],
        "ETag": [
            "W\/\"4e2-jccTJQbTGWrdlwKu5W\/tXAq6oic\""
        ],
        "Vary": [
            "Accept-Encoding"
        ],
        "set-cookie": [
            "sails.sid=s%3ANbFkdEhd76Jmfwh9g6cq_JdypMwST24k.oWmMF53pgbYh5SBtavSUDhOvJa070ku3NDCytMccm6w; Path=\/; HttpOnly"
        ]
    },
    "data": {
        "args": [],
        "data": {
            "_id": "5bce15a131c96f012b74ee39",
            "channels": {
                "email": {
                    "address": "dsmith+5bce14d13101d@cordial.com.sink.sparkpostmail.com",
                    "subscribeStatus": "subscribed"
                }
            },
            "lists": [
                "100k-sink"
            ],
            "lastModified": "2019-07-18T15:10:59+0000",
            "createdAt": "2018-10-22T18:23:29+0000",
            "name": "Lucya",
            "mdtLastSent": {
                "5c99a3b610986b7e3ce5a4b8": {
                    "sec": 1556892890,
                    "usec": 0
                }
            },
            "age": 1,
            "cID": "5bce15a131c96f012b74ee39",
            "id": "5bce15a131c96f012b74ee39"
        },
        "files": [],
        "form": [],
        "headers": {
            "x-forwarded-proto": "https",
            "x-forwarded-port": "443",
            "host": "postman-echo.com",
            "x-amzn-trace-id": "Root=1-6267e71f-66aa6700217d097f20dbc636",
            "content-length": "437",
            "authorization": "Basic Y29yZGlhbF9zYXlzOmhlbGxv",
            "content-type": "application\/json",
            "user-agent": "Cordial Platform"
        },
        "json": {
            "_id": "5bce15a131c96f012b74ee39",
            "channels": {
                "email": {
                    "address": "dsmith+5bce14d13101d@cordial.com.sink.sparkpostmail.com",
                    "subscribeStatus": "subscribed"
                }
            },
            "lists": [
                "100k-sink"
            ],
            "lastModified": "2019-07-18T15:10:59+0000",
            "createdAt": "2018-10-22T18:23:29+0000",
            "name": "Lucya",
            "mdtLastSent": {
                "5c99a3b610986b7e3ce5a4b8": {
                    "sec": 1556892890,
                    "usec": 0
                }
            },
            "age": 1,
            "cID": "5bce15a131c96f012b74ee39",
            "id": "5bce15a131c96f012b74ee39"
        },
        "url": "https:\/\/postman-echo.com\/post"
    },
    "error": null
}

Parameters

Parameter Description Required Expected Default
url URL for the externally hosted endpoint required valid URL NA
payload payload for the request containing the data update required an array of key/values pairs NA
options Allows for the configuration of options such as HTTP request headers or maximum wait time. optional an array of key/values pairs []

Set the URL

For the purpose of this example, we'll use the server accessible by the link below.

In the examples above, we assume the contact data with firstName, lastName, email, and id properties are stored at this same location.

Set the payload

Payload is a data set to be uploaded to the external server. It is an array of key/value pairs that are supported by external server API.

In the following example, the array is defined within the method.

[
"firstName" => "John",
"lastName" => "Smith",
"email" => "jsmith@gmail.com",
"id" => 101]

In this next example, the system variable $contact was used as the payload parameter.

['contact_object' => $contact]

Using this approach, you should ensure that the data properties expected by the external server are available in the contact object.

Set options

This parameter allows for the configuration of additional processing options. Within the options you can set headers, timeout, and cache minutes.

Setting HTTP request headers pass additional information to server with a request. It is an array of header names and values.

Headers can be used for authorization, as in the following example.

['headers'=>['Authorization' => 'Basic <base64 encoded username:password>']]

Other headers can be passed as supported by the target API.