From RPTools Wiki
Jump to navigation Jump to search Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.5.0
Perform an HTTP post request to the specified URL to create a resource.

Usage, payload, mediaType, getFullResponse), payload, mediaType, headers, getFullResponse)


  • url - String containing the URL to the resource or collection of resources.
  • payload - JSON object containing the key:value pairs.
  • mediaType - String containing a MIME type and charset. See example, but note that any character encoding other than UTF-8 will be extremely difficult to produce in MapTool.
  • headers - JSON object containing header key:value pairs where the value will be an array of 1 or more strings. Example: '{"X-Header-Name": ["value"]}'
  • getFullResponse - Boolean (0:1). True(1) to get full response.


HTTP response as JSON (if full response) or server response, usually JSON but can be XML, HTML, or other formats.

Note: If a post fails with getFullResponse set to false, an error will be produced with a Status Code of 400. Set getFullResponse to true(1) for more detail.


Create a user with a post request.
[h: baseurl = ""]
[h: path = "/api/users"]
[h: mediaType = "application/json; charset=utf-8"]
[h: getFullResponse = 1]

[h: payload = '{ "name": "morpheus", "job": "leader" }']

[h: response = + path, payload, mediaType, getFullResponse)]

[r: json.indent(response, 2)]


  "status": 201,
  "headers":   {
    "access-control-allow-origin": ["*"],
    "cf-ray": ["4b92503c1f49772a-LAX"],
    "content-length": ["84"],
    "content-type": ["application/json; charset=utf-8"],
    "date": ["Sun, 17 Mar 2019 22:13:19 GMT"],
    "etag": ["W/\"54-Iq8tAhIi7JekRXqEAyUkl9PsnwI\""],
    "expect-ct": ["max-age=604800, report-uri=\"\""],
    "server": ["cloudflare"],
    "set-cookie": ["__cfduid=dd8f9e69613d9ab995b4365e36bcc2e181552860799; expires=Mon, 16-Mar-20 22:13:19 GMT; path=/;; HttpOnly"],
    "x-powered-by": ["Express"]
  "body":   {
    "name": "morpheus",
    "job": "leader",
    "id": "996",
    "createdAt": "2019-03-17T22:17:50.616Z"

See Also