HTTP POST

HTTP POST

Type: http-post  ·  Package: HTTP Activities v1.0.5  ·  Output: ZoanHttpResponse

Sends a POST request, usually to create a resource or send data to an API: register a customer, submit a form, trigger an action. Unlike GET, it carries a body (body) with the data.

How it works

Sends body to url and returns a ZoanHttpResponse.

• Body: with the default contentType (application/json), body is converted to JSON — a dictionary is sent as an object, a list as an array. With any other contentType, body is sent as text, as is. Always UTF-8. See body and Content-Type.
• Status codes: 2xx succeeds; any other code makes the activity fail — see what makes the activity fail.
• Timeouts: 30 s to connect and, by default, 5 min for the whole request (timeout parameter). When they run out, the activity fails with a normal error that Try / Catch and Retry catch — see timeouts.
• Not idempotent: repeating a POST usually creates the resource twice. Before wrapping it in Retry, make sure the API tolerates it (for example with an idempotency key in headers, if the API offers one).

Required parameters

Parameter	Type	Default	Description
url	string	—	Absolute request URL (https://…).
body	object	—	The body: a dictionary or list (sent as JSON) or a text (for other contentType values). With a JSON contentType, a text is sent as a quoted JSON string; if you have JSON in a text, use parseJson(text).

Optional parameters

Parameter	Type	Default	Description
contentType	string	"application/json"	Media type of the body, without parameters (e.g. application/json, text/xml, application/x-www-form-urlencoded). charset=utf-8 is added for you.
headers	Dictionary	—	Extra headers (name → value), in the JSON editor. Content headers are ignored: use contentType. See headers.
authorization	Dictionary	—	Authentication in the JSON editor: bearer, basic or apikey. See authentication.
timeout	int	300	Seconds to wait for the whole request (connection, sending and answer); maximum 3600, decimals allowed (0.5). Since version 1.0.5. See timeouts.

Output

Returns a ZoanHttpResponse with .StatusCode (2xx; APIs often answer 201 on create), .Ok (always true in an output you receive), .Body (JSON → dictionary/list; anything else → text; empty → "") and .Headers. Many APIs return the created resource with its new id in .Body, or its location in resp.Headers["Location"].

Common errors

Message	Cause and fix
The server answered HTTP 400 (Bad Request) to the POST request.	The server rejected the request (400 invalid data, 401/403 authentication, 409 duplicate, 5xx server error). The message does not include the response body: check the format the API expects. To handle it, use Try / Catch.
The format of value 'application/json; charset=utf-8' is invalid.	contentType has parameters. Keep only the media type (application/json); the UTF-8 charset is added for you.
No such host is known. (or another system network error)	There was no response (host name, network, certificate). error.Type is "HttpRequestException".
The POST request to api.example.com did not finish within 300 s (timeout). Raise 'timeout' if the service takes longer.	The server did not answer within timeout. error.Type is \"TimeoutException\": catch it with Try / Catch or retry with Retry; if the API is slow by nature, raise timeout. If connecting fails, the message says Could not connect to … within 30 s.
An invalid request URI was provided. Either the request URI must be an absolute URI or BaseAddress must be set.	url is not absolute. Include https://.
'url' is required.	The url expression evaluated to null.

Since version 1.0.5, if the server does not answer in time the activity fails with a catchable error (TimeoutException); before, the execution ended as cancelled — see timeouts.

Example

Create a customer by sending an object as JSON and use the id the API returns:

HTTP POST
  url  = "https://api.erp.com/customers"
  body = new Dictionary<string, object> { ["name"] = customerName, ["taxId"] = taxId, ["active"] = true }
  authorization = { "type": "bearer", "token": credential("erp-api")["value"] }
  → output: resp

Set Variable   name = newId   value = resp.Body["id"]
Log   message = "Customer created with id " + newId + " (HTTP " + resp.StatusCode + ")"

Send XML to a service that does not use JSON:

HTTP POST
  url         = "https://services.example.com/invoices"
  contentType = "text/xml"
  body        = invoiceXml
  → output: resp
Log   message = "Service response: " + str(resp.Body)

Body as an object

The easiest option is to pass an object in body: Zoan Automation serializes it to JSON for you. Build it with new Dictionary<string, object> { ["field"] = value }, with newDict() and dictSet(...), or from a JSON text with parseJson(text). If the API expects another format (XML, plain text, form), pass a text and set contentType.

Related activities

• HTTP PUT / HTTP PATCH — update an existing resource.
• HTTP GET — read data.
• Try / Catch — handle error responses.