1. HTTP Functions

HTTP Functions

1.1. Introduction ↑

The ACF language includes built-in HTTP functions for calling web services and APIs directly from ACF code. They can be used for REST APIs, JSON APIs, XML/SOAP endpoints, form posts, synchronization tasks, and other integrations where a FileMaker solution needs to send or retrieve data over HTTP or HTTPS.

The main request functions return the response body as a string. After each request, the system variable HTTP_STATUS_CODE contains the HTTP status code returned by the server, such as 200, 201, 204, 400, 401, or 500. The system variable HTTP_HEADERS contains the response headers from the last HTTP request.

Headers are supplied as a string with one header per line. Use carriage return (\r) between header lines.

1.2. Request Functions ↑

1.2.1. HTTP_GET ↑

Syntax: string HTTP_GET(string url {, string headers {, string authenticationHeader}})
Description: Sends an HTTP GET request and returns the response body.
Parameters:
- url: The URL to request. Query parameters should already be URL encoded.
- headers: Optional header string, one header per line separated by \r.
- authenticationHeader: Optional authentication header, often created with HTTP_BASIC_AUTH(...).
Returns: The response body as a string.

Example:

function GetCustomerFromAPI(string customerId)
    string url = "https://api.example.com/customers/" + URL_ENCODE(customerId);
    string headers = "Accept: application/json";
    string response = HTTP_GET(url, headers);

    if (HTTP_STATUS_CODE != 200) then
        throw format("HTTP GET failed. Status=%d Response=%s", HTTP_STATUS_CODE, response);
    end if

    return response;
end

1.2.2. HTTP_POST ↑

Syntax: string HTTP_POST(string url, string postData {, string headers {, string authenticationHeader}})
Description: Sends an HTTP POST request and returns the response body.
Parameters:
- url: The URL to request.
- postData: The request body.
- headers: Optional header string, one header per line separated by \r.
- authenticationHeader: Optional authentication header.
Returns: The response body as a string.

Example:

function CreateRemoteCustomer(JSON customer)
    string url = "https://api.example.com/customers";
    string headers = "Content-Type: application/json\rAccept: application/json";
    string response = HTTP_POST(url, string(customer), headers);

    if (HTTP_STATUS_CODE < 200 || HTTP_STATUS_CODE >= 300) then
        throw format("HTTP POST failed. Status=%d Response=%s", HTTP_STATUS_CODE, response);
    end if

    return response;
end

1.2.3. HTTP_PUT ↑

Syntax: string HTTP_PUT(string url, string postData {, string headers {, string authenticationHeader}})
Description: Sends an HTTP PUT request. PUT is commonly used to replace or update a complete resource.
Returns: The response body as a string.

Example:

string response = HTTP_PUT(
    "https://api.example.com/customers/123",
    string(customerJson),
    "Content-Type: application/json\rAccept: application/json"
);

1.2.4. HTTP_PATCH ↑

Syntax: string HTTP_PATCH(string url, string postData {, string headers {, string authenticationHeader}})
Description: Sends an HTTP PATCH request. PATCH is commonly used to update part of a resource.
Returns: The response body as a string.

Example:

JSON patch = JSON("status", "closed");
string response = HTTP_PATCH(
    "https://api.example.com/cases/445",
    string(patch),
    "Content-Type: application/json\rAccept: application/json"
);

1.2.5. HTTP_DELETE ↑

Syntax: string HTTP_DELETE(string url, string postData {, string headers {, string authenticationHeader}})
Description: Sends an HTTP DELETE request. Some APIs require an empty body, while others accept a small JSON or form body explaining the delete operation.
Returns: The response body as a string.

Example:

string response = HTTP_DELETE(
    "https://api.example.com/customers/123",
    "",
    "Accept: application/json"
);

if (HTTP_STATUS_CODE != 200 && HTTP_STATUS_CODE != 204) then
    throw format("HTTP DELETE failed. Status=%d Response=%s", HTTP_STATUS_CODE, response);
end if

1.3. Authentication ↑

1.3.1. HTTPBASICAUTH ↑

Syntax: string HTTP_BASIC_AUTH(string user, string password {, string realm})
Description: Creates a Basic Authentication header for use with HTTP_GET, HTTP_POST, HTTP_PUT, HTTP_PATCH, or HTTP_DELETE.
Parameters:
- user: Username.
- password: Password.
- realm: Optional realm text.
Returns: A header string suitable for the authentication parameter.

Example:

string response = HTTP_GET(
    "https://api.example.com/private/status",
    "Accept: application/json",
    HTTP_BASIC_AUTH("apiuser", "secret")
);

You can also include authentication directly in the regular header string if the API uses another method, such as Bearer tokens:

string headers =
    "Accept: application/json\r" +
    "Authorization: Bearer " + accessToken;

string response = HTTP_GET("https://api.example.com/me", headers);

1.4. URL Encoding ↑

1.4.1. URL_ENCODE ↑

Syntax: string URL_ENCODE(string text)
Description: Encodes a string so it can safely be used inside a URL or query parameter.

Example:

string searchText = "ACF Plugin PDF & JSON";
string url = "https://api.example.com/search?q=" + URL_ENCODE(searchText);
string response = HTTP_GET(url, "Accept: application/json");

1.4.2. URL_DECODE ↑

Syntax: string URL_DECODE(string text)
Description: Decodes a URL-encoded string.

Example:

string normalText = URL_DECODE("ACF%20Plugin%20PDF%20%26%20JSON");

1.5. Status Codes ↑

After any HTTP request, inspect HTTP_STATUS_CODE to decide whether the request succeeded.

Common success codes:

Code	Meaning
`200`	OK
`201`	Created
`202`	Accepted
`204`	No content

Common error codes:

Code	Meaning
`400`	Bad request
`401`	Unauthorized
`403`	Forbidden
`404`	Not found
`409`	Conflict
`429`	Too many requests
`500`	Server error

Typical check:

string response = HTTP_GET(url, headers);
if (HTTP_STATUS_CODE < 200 || HTTP_STATUS_CODE >= 300) then
    throw format("HTTP request failed. Status=%d Response=%s", HTTP_STATUS_CODE, response);
end if

1.6. Response Headers ↑

After any HTTP request, HTTP_HEADERS contains the response headers from the last request as text.

Example:

string response = HTTP_GET(url, headers);
string responseHeaders = HTTP_HEADERS;

if (HTTP_STATUS_CODE == 200) then
    print responseHeaders;
end if

1.7. Cookies ↑

The HTTP functions do not keep an automatic cookie jar. Cookies returned by the server are available in HTTP_HEADERS as ordinary response headers. To send a cookie on a later request, add a Cookie: line to the request header string.

Simple example with one session cookie:

string loginResponse = HTTP_POST(
    "https://api.example.com/login",
    string(loginJson),
    "Content-Type: application/json\rAccept: application/json"
);

if (HTTP_STATUS_CODE != 200) then
    throw format("Login failed. Status=%d Response=%s", HTTP_STATUS_CODE, loginResponse);
end if

string responseHeaders = HTTP_HEADERS;
string sessionCookie = between(responseHeaders, "Set-Cookie: ", ";");

if (sessionCookie == "") then
    throw "Login did not return a session cookie.";
end if

string headers =
    "Accept: application/json\r" +
    "Cookie: " + sessionCookie;

string privateData = HTTP_GET("https://api.example.com/private/data", headers);

If the server returns several Set-Cookie headers, collect the name=value part from each one and send them together in one Cookie: header separated by semicolon and space:

string headers =
    "Accept: application/json\r" +
    "Cookie: sessionid=abc123; theme=dark";

1.8. Headers ↑

Headers are supplied as a single string. Separate multiple headers with carriage return (\r):

string headers =
    "Content-Type: application/json\r" +
    "Accept: application/json\r" +
    "X-Client: FileMaker";

Common headers:

Header	Typical use
`Accept: application/json`	Ask for JSON response.
`Content-Type: application/json`	Send JSON request body.
`Content-Type: text/xml`	Send XML/SOAP request body.
`Authorization: Bearer <token>`	Bearer-token authentication.
`Cookie: name=value`	Send cookies manually.

1.9. JSON API Example ↑

function LookupCompany(string orgNr)
    orgNr = regex_replace("[^0-9]", orgNr, "");

    string url = "https://data.brreg.no/enhetsregisteret/api/enheter/" + orgNr;
    string headers = "Accept: application/vnd.brreg.enhetsregisteret.enhet.v2+json;charset=UTF-8";
    string response = HTTP_GET(url, headers);

    if (HTTP_STATUS_CODE != 200) then
        throw format("Company lookup failed. Status=%d Response=%s", HTTP_STATUS_CODE, response);
    end if

    JSON data = response;
    return JSON(
        "name", data["navn"],
        "zip", data["forretningsadresse.postnummer"],
        "city", data["forretningsadresse.poststed"]
    );
end

1.10. XML API Example ↑

function SendXmlMessage(string endpoint, XML message)
    string headers = "Content-Type: text/xml\rAccept: text/xml";
    string response = HTTP_POST(endpoint, string(message), headers);

    if (HTTP_STATUS_CODE < 200 || HTTP_STATUS_CODE >= 300) then
        throw format("XML API call failed. Status=%d Response=%s", HTTP_STATUS_CODE, response);
    end if

    return response;
end

1.11. Notes ↑

Use HTTP_GET for retrieval operations where all input can be represented in the URL.
Use HTTP_POST when sending a request body, creating records, posting forms, or calling APIs that require POST.
Use HTTP_PUT, HTTP_PATCH, and HTTP_DELETE when an API explicitly requires those methods.
Always inspect HTTP_STATUS_CODE; many APIs return useful error details in the response body.
Use URL_ENCODE(...) for query parameter values, not for the whole URL.
For JSON request bodies, create a JSON value and pass string(myJson) as the request body.
For XML request bodies, create an XML value and pass string(myXml) as the request body.