Home
/
Docs
/
Articles Report Writer
/
Report Components
/
REST API Post / Put

REST API Post / Put

The REST API POST / PUT / PATCH component sends an HTTP request to a REST API endpoint as the report prints. Drop it on a band and configure the endpoint URL and request body. When that band prints, Articles sends the request automatically. Use it to push data to an external system as part of a report run — for example posting transactions to an accounting API, updating records in a CRM, or triggering a workflow.

This component is invisible at runtime — it has no visible output on the printed page. It only appears in the designer as a small blue label showing the HTTP method and endpoint URL.

When to Use REST API POST / PUT / PATCH

Use this component when a report needs to:

Post data to an external API as each record prints — for example sending each invoice to an accounting system
Update a record in an external system when a report confirms it has been processed
Trigger a webhook or workflow for each master record in a report
Push report results to an external data store

If you need to read data from a REST API, use REST Table instead. This component is for sending data only.

Adding REST API POST / PUT / PATCH to Your Report

Find the REST API POST / PUT / PATCH component in the report designer component panel
Drag it onto the band that should trigger the request — typically a MasterData band so it fires once per record
Set EndpointURL to the full URL of the API endpoint
Set Kind to POST, PUT, or PATCH depending on what the API expects
Set BodyMode and configure the request body
Set AuthType and the appropriate credentials if the API requires authentication
Handle the OnResponse event if you need to react to the API response

The component fires automatically each time the band it is placed on prints. To fire it manually from script instead, set Enabled to False and call Execute from a band event.

Properties

EndpointURL
The full URL of the REST API endpoint. For example https://api.example.com/v1/invoices. The URL is trimmed of whitespace automatically — accidental spaces or newlines in the designer will not cause 404 errors.

Kind
The HTTP method to use. Options are:

rkPost — HTTP POST (default). Use for creating new records.
rkPut — HTTP PUT. Use for replacing an existing record.
rkPatch — HTTP PATCH. Use for partially updating an existing record.

ContentType
The Content-Type header sent with the request. Default is application/json. Change this if the API expects a different format such as application/x-www-form-urlencoded.

Enabled
When True (default), the component fires automatically when the band prints. Set to False to suppress automatic firing — you can then call Execute from script manually when needed.

ExtraHeaders
Additional HTTP headers to send with the request. Enter one header per line in the format HeaderName=HeaderValue. Use this for API-specific headers that are not covered by the authentication properties.

LastStatusCode
Read-only. The HTTP status code returned by the last request. 200-299 indicates success. 400-499 indicates a client error. 500+ indicates a server error. 0 means the request failed before reaching the server.

LastResponse
Read-only. The response body returned by the API after the last request. Read this in the OnResponse event to process the API’s reply.

LastError
Read-only. Contains an error description if the last request failed. Empty if the last request succeeded.

Building the Request Body

The BodyMode property controls how the request body is built. Three modes are available:

rbmTemplate (default)
The body is taken from BodyTemplate with {expression} tokens evaluated at runtime. Any text inside curly braces is evaluated as a FastReport expression or report variable and the result is substituted into the body. Text outside curly braces is sent as-is.

Example BodyTemplate for posting an invoice as JSON:

{
  "invoiceNumber": "{FDQueryInvoices.'InvoiceNumber'}",
  "customerName": "{FDQueryInvoices.'CustomerName'}",
  "amount": {FDQueryInvoices.'Amount'},
  "invoiceDate": "{FDQueryInvoices.'InvoiceDate'}"
}

Articles evaluates each {expression} token using the current report variable values and field values when the band prints. To include a literal curly brace in the output, double it: {{ produces { and }} produces }.

rbmExpression
The entire body is produced by evaluating a single PascalScript expression set in BodyExpression. The expression result becomes the request body. Use this when you need to build the body programmatically in script rather than using a template.

Example BodyExpression — calling a script function that builds JSON:

BuildInvoiceJSON(FDQueryInvoices.'InvoiceNumber')

rbmPassthrough
The body is taken from BodyTemplate exactly as typed with no processing at all. No tokens are evaluated, no substitution occurs. Use this when the body is a fixed string that never changes, or when you set the body entirely from script before Execute fires.

Authentication

ratNone — no authentication. Default.
ratBearerToken — adds Authorization: Bearer your-token. Set BearerToken.
ratBasicAuth — adds HTTP Basic authentication. Set Username and Password.
ratAPIKey — sends an API key either as a header or a query parameter. Set APIKeyValue and choose APIKeyLocation:

raklHeader — sends the key as a request header. Set APIKeyHeader to the header name (default is X-Api-Key)
raklQueryParam — appends the key to the URL as a query parameter. Set APIKeyParam to the parameter name (default is api_key)

ratClientCreds — OAuth2 client credentials flow. Set TokenURL, ClientID, ClientSecret, and optionally Scope. Articles fetches a token, caches it, and refreshes it automatically when it expires (60 seconds before expiry).

Events

OnResponse
Fires after every request completes — whether it succeeded or failed. Use this to check the response and take action based on the result. The event receives the HTTP status code, the response body, and any error message.

procedure RESTAPIPutPost1OnResponse(Sender: TObject;
  StatusCode: Integer; const Response, Error: String);
begin
  if StatusCode >= 400 then
    ShowMessage('API error ' + IntToStr(StatusCode) + ': ' + Error)
  else
    // Success - optionally read Response to get the API's reply
    Report.Variables['LastAPIResponse'] := Response;
end;

OnBeforeExecute
Fires just before the HTTP request is sent. Use this to change the EndpointURL, update the BodyTemplate, or set credentials dynamically based on the current record before the request fires.

Calling Execute from Script

To control exactly when the request fires — for example only for records that meet a condition — set Enabled to False and call Execute from a band event:

procedure MasterDataOnBeforePrint(Sender: TObject);
begin
  // Only send to the API if the invoice is over $1000
  if FDQueryInvoices.FieldByName('Amount').AsFloat > 1000 then
  begin
    // Optionally update the URL or body before firing
    RESTAPIPutPost1.EndpointURL :=
      'https://api.example.com/invoices/' +
      FDQueryInvoices.FieldByName('InvoiceID').AsString;
    RESTAPIPutPost1.Execute;

    // Check the result
    if RESTAPIPutPost1.LastStatusCode >= 400 then
      ShowMessage('Failed to post invoice: ' + RESTAPIPutPost1.LastError);
  end;
end;

Checking the Result

After Execute fires — either automatically or from script — check LastStatusCode to verify the request succeeded:

200-299 — success
400-499 — client error — the request was rejected by the API. Check LastError and LastResponse for details.
500+ — server error — the API encountered an internal problem
0 — the request never reached the server — network error or invalid URL. Check LastError.

The Designer Label

In the designer, the component shows as a small blue rectangle. The label displays the HTTP method and endpoint URL so you can see at a glance what each component does:

[POST] RESTAPIPutPost1 → https://api.example.com/invoices

If the endpoint URL is long, the label truncates it with an ellipsis. The full URL is always available in the Object Inspector.

Common Problems

The component fires but nothing happens — no error, no response
Check that Enabled is True. Also check that EndpointURL is set. If both are correct, add an OnResponse handler and check what StatusCode and Error contain after the request.

LastStatusCode is 0 and LastError mentions a network error
The request could not reach the server. Check the URL for typos, verify the server is reachable from the machine running the report, and check firewall or proxy settings.

The API returns 400 Bad Request
The request body is malformed. Check the BodyTemplate for syntax errors — missing quotes, unclosed braces, or invalid JSON. Also check that ContentType matches what the API expects.

Template tokens are not being substituted
Check that BodyMode is set to rbmTemplate. If BodyMode is rbmPassthrough, the template is sent exactly as typed with no substitution. Also check the token syntax — tokens must use single curly braces: {expression} not {{expression}}.

The OAuth2 token is being fetched on every request
Articles caches the token and refreshes it 60 seconds before expiry. If the token is being fetched every time, check that TokenURL, ClientID, and ClientSecret are set correctly and that the token endpoint is returning an expires_in value. Without expires_in the cache cannot determine when to refresh.

The component fires too many times
The component fires every time the band it is placed on prints. If it is on a DetailData band it fires once per detail row. Move it to the MasterData band if you only want one request per master record, or set Enabled to False and call Execute from script with a condition.

Articles Report Writer