{"title":"Create and call an OData V4 unbound action","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-unbound-action/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-unbound-action, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-unbound-action","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Create an OData V4 unbound action in AL, publish a codeunit as a web service, and send authenticated JSON requests to call its procedures in Business Central.","date":"2026-10-29","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Create and call an OData V4 unbound action","slug":"create-and-call-an-odata-v4-unbound-action","at":0,"chars":8207},{"level":2,"title":"Prerequisites for the codeunit example","slug":"prerequisites-for-the-codeunit-example","at":249,"chars":816},{"level":2,"title":"Declare the codeunit procedures","slug":"declare-the-codeunit-procedures","at":1065,"chars":1908},{"level":2,"title":"Publish the codeunit as a web service","slug":"publish-the-codeunit-as-a-web-service","at":2973,"chars":573},{"level":2,"title":"Call a procedure with an HTTP POST request","slug":"call-a-procedure-with-an-http-post-request","at":3546,"chars":3034},{"level":3,"title":"Test the service with a simple parameter","slug":"test-the-service-with-a-simple-parameter","at":4651,"chars":616},{"level":3,"title":"Pass JSON text as a parameter","slug":"pass-json-text-as-a-parameter","at":5267,"chars":727},{"level":3,"title":"Call a procedure that returns no value","slug":"call-a-procedure-that-returns-no-value","at":5994,"chars":586},{"level":2,"title":"Migrate supported codeunit operations from SOAP","slug":"migrate-supported-codeunit-operations-from-soap","at":6580,"chars":556},{"level":2,"title":"Troubleshoot unbound-action requests","slug":"troubleshoot-unbound-action-requests","at":7136,"chars":696},{"level":2,"title":"Related information","slug":"related-information","at":7832,"chars":375}],"text":"# Create and call an OData V4 unbound action\nUse an OData V4 unbound action to call an AL codeunit procedure without addressing a specific record. This article shows how to publish a codeunit, send procedure parameters as JSON, and read the result.\n## Prerequisites for the codeunit example\n An AL extension project with object ID 50100 in its app.json ID ranges.\n A Business Central test environment and permission to publish web services. The calling identity needs permission to execute the codeunit and perform any operations that its procedures use.\n An HTTP client and authentication for your environment. The examples use OAuth. For Business Central online, use an OAuth access token. For on-premises environments, use the authentication configured for the server. See Using OAuth to authorize Business Central web services<../webservices/authenticate-web-services-using-oauth>.\n For on-premises environments, enabled OData V4 services. See Business Central Server instance settings<../administration/server-instance-settings#expose-odata-and-api-services>.\n## Declare the codeunit procedures\nDefine public procedures in a codeunit. These codeunit actions don't require the `[ServiceEnabled]` attribute used for page-bound actions.\nThe following codeunit provides three operations:\nProcedure|Parameter|Successful result\nPing|input: Integer|The supplied integer with its sign reversed, except for the minimum Integer value.\nDelay|delayMilliseconds: Integer|Waits for the specified nonnegative number of milliseconds and returns no value.\nGetLengthOfStringWithConfirmation|inputJson: Text|The length of str when confirm is true; otherwise `-1`, subject to the input requirements below.\n```al\ncodeunit 50100 \"MiscOperations\"\n{\n    procedure Ping(input: Integer): Integer\n    begin\n        exit(-input);\n    end;\n\n    procedure Delay(delayMilliseconds: Integer)\n    begin\n        Sleep(delayMilliseconds);\n    end;\n\n    procedure GetLengthOfStringWithConfirmation(inputJson: Text): Integer\n    var\n        InputObject: JsonObject;\n        ConfirmToken: JsonToken;\n        StringToken: JsonToken;\n    begin\n        InputObject.ReadFrom(inputJson);\n\n        if not InputObject.Get('confirm', ConfirmToken) then\n            exit(-1);\n\n        if not ConfirmToken.AsValue().AsBoolean() then\n            exit(-1);\n\n        if not InputObject.Get('str', StringToken) then\n            exit(-1);\n\n        exit(StrLen(StringToken.AsValue().AsText()));\n    end;\n}\n```\nFor GetLengthOfStringWithConfirmation, pass inputJson as text containing a JSON object. When present, confirm should be a Boolean and str should be a string. The procedure returns `-1` if confirmation is missing or false, or if str is missing. Invalid JSON or incompatible values can cause a runtime error instead.\nThe separate checks ensure that each property is available before the code converts it. AL and expressions don't short-circuit, so a compound condition isn't a safe way to guard these conversions.\n## Publish the codeunit as a web service\n1. Build and publish the extension to your test environment.\n1. In Business Central, use Search to find and open the Web Services page.\n1. Select New.\n1. Set Object Type to Codeunit, Object ID to 50100, and Service Name to MyOperations.\n1. Select Published.\nThe action URL uses the service name MyOperations, not the codeunit name MiscOperations. Construct the URL as shown in the next section. For codeunits, the generated OData URL can point to documentation instead of an action endpoint.\nSee ../webservices/publish-web-service.\n## Call a procedure with an HTTP POST request\nJoin the published service name and the procedure name with an underscore:\n```http\nPOST <BaseUrl>/ODataV4/<ServiceName>_<ProcedureName>?company=<CompanyName>\n```\nReplace `<BaseUrl>` with your environment's OData URL prefix, excluding `/ODataV4`. For Business Central online, use `https://api.businesscentral.dynamics.com/v2.0/<TenantId>/<EnvironmentName>`. Replace `<TenantId>` and `<EnvironmentName>` with your tenant ID and environment name. For on-premises environments, ask your administrator for the configured OData URL prefix.\nFor this example, `<ServiceName>` is MyOperations. Use the company name or company ID for company. URL-encode the company name. The example uses a company named `CRONUS USA Inc.`; replace it with a company in your environment.\nFor OAuth authentication, replace `<AccessToken>` with an access token for your environment.\nSend a JSON object whose property names match the declared procedure parameter names, including their casing. For inputJson, the value must be a JSON string containing JSON text, not a nested JSON object.\n### Test the service with a simple parameter\nStart with Ping to check the service URL, authentication, and parameter format before trying the JSON-text example:\n```http\nPOST <BaseUrl>/ODataV4/MyOperations_Ping?company=CRONUS%20USA%20Inc. HTTP/1.1\nAuthorization: Bearer <AccessToken>\nContent-Type: application/json\nAccept: application/json;odata.metadata=minimal\n\n{\n  \"input\": 42\n}\n```\nA successful request returns `200 OK` with `-42` in the response's value property.\nFor Ping, use input values from `-2147483647` to `2147483647`. The minimum Integer value, `-2147483648`, can't be negated within the Integer range.\n### Pass JSON text as a parameter\n```http\nPOST <BaseUrl>/ODataV4/MyOperations_GetLengthOfStringWithConfirmation?company=CRONUS%20USA%20Inc. HTTP/1.1\nAuthorization: Bearer <AccessToken>\nContent-Type: application/json\nAccept: application/json;odata.metadata=minimal\n\n{\n  \"inputJson\": \"{\\\"str\\\":\\\"Hello world!\\\",\\\"confirm\\\":true}\"\n}\n```\nThe str value, `Hello world!`, has 12 characters. A successful response returns `200 OK` with that length in the value property:\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json;odata.metadata=minimal\n\n{\n  \"@odata.context\": \"<BaseUrl>/ODataV4/$metadata#Edm.Int32\",\n  \"value\": 12\n}\n```\nThe `@odata.context` annotation shown here corresponds to the requested minimal-metadata JSON format.\n### Call a procedure that returns no value\nThe Delay procedure takes a number of milliseconds but has no return value:\n```http\nPOST <BaseUrl>/ODataV4/MyOperations_Delay?company=CRONUS%20USA%20Inc. HTTP/1.1\nAuthorization: Bearer <AccessToken>\nContent-Type: application/json\n\n{\n  \"delayMilliseconds\": 100\n}\n```\nAfter the procedure completes successfully, the service returns:\n```http\nHTTP/1.1 204 No Content\n```\nUse a small, nonnegative value for delayMilliseconds. This example doesn't validate the parameter. A value of `-1` can wait indefinitely, and values below `-1` cause an error.\n## Migrate supported codeunit operations from SOAP\nOData V4 unbound actions can expose supported public codeunit procedures as web-service operations. When migrating from SOAP, review the procedure signatures and update the client's request and response handling. Don't assume that changing the URL is sufficient.\nProcedures with ordinary var parameters or array parameters aren't exposed through this codeunit action path. Use supported parameter and return types, and inspect `<BaseUrl>/ODataV4/$metadata` to verify the actions available to your client.\n## Troubleshoot unbound-action requests\n If the action isn't found, confirm that codeunit 50100 is published as MyOperations. Use POST and the exact service and procedure names separated by an underscore.\n If a parameter is missing, use its declared name and casing in the JSON body. Use input for Ping, delayMilliseconds for Delay, and inputJson for GetLengthOfStringWithConfirmation. The inputJson value must be a JSON string, not a nested object.\n If the JSON conversion fails, check both the outer request body and the JSON text inside inputJson. This sample doesn't convert every invalid input into `-1`.\n If execution is denied, check the calling identity's permissions and authentication.\n## Related information\nCreate and call an OData V4 bound action<devenv-creating-and-interacting-with-odatav4-bound-action>\n../webservices/publish-web-service\nUsing OAuth to authorize Business Central web services<../webservices/authenticate-web-services-using-oauth>\n../webservices/odata-known-limitations\n../webservices/handling-ui-interaction-when-working-with-web-services"}