Requests and Responses
On this page
Request headers and body
- A call to an API route carries the bearer token, or the caller's Windows credentials when the instance uses Windows authentication.
- A call to an API route must use HTTPS. A plain-HTTP request receives
505 HTTP Version Not Supportedwith the message "HTTP protocol is not supported." - A request whose body is
multipart/*is rejected with415 Unsupported Media Typeand a message directing the caller to JSON. - A request whose
Content-Lengthis above 100 KB and also above the API's configured maximum request size is rejected with413 Request Entity Too Large, quoting both sizes. The shipped maximum request size is 50 MB. Attachment content travels as base64, so the usable file size is roughly three quarters of that. The attachment size limit is a separate setting held in the database:GET /V1/SystemSettingsreturns it in megabytes, or0when the attachment limit is switched off. Check that value before uploading; the request size limit is separate and larger. - A trailing slash on the path is ignored:
.../Profileand.../Profile/are the same route. - Query-string values reach the product already decoded, and a
+is read as a space. Percent-encode spaces,&,=,#,+, and%in a value. - The response is JSON unless the request's
Acceptheader asks for XML. In XML, the envelope's root element isResult.
The two token endpoints are outside these checks: the HTTPS, media type,
and body size refusals and the choice between JSON and XML do not apply to
them. A token request of an unsupported content type is refused with a
plain-text 400 answer instead.
The response envelope
A call that reaches one of the API's JSON routes answers the same four-field envelope, whether the call succeeded or failed:
| Field | Meaning |
|---|---|
success |
Whether the call succeeded. |
errorCode |
0 on success, 101 on failure. There is no other value, so errorCode cannot tell failures apart; the distinguishing information is in errorText. |
errorText |
The error message when the call failed. |
responseObject |
The result of the call. It is null when the call failed with an error; when a workflow action aborts, it still carries the action's messages (see Workflow actions that abort). |
A failed call on these routes still answers with HTTP status 200, so
branch on success, not on the HTTP status code.
Answers that do not use the envelope include:
- the
415,413, and505refusals described above, which are sent before the call runs; - a request the API refuses as unauthorized, which gets the web framework's
own unauthorized answer (
401); - the token endpoints, including a token answer, a refused grant, and the
plain-text
400answer to a token request of an unsupported content type; - the lifecycle routes;
- the root page, which is an HTML page;
- attachment downloads;
- the route that runs an action from a signed link, which renders an HTML page;
V1/ai-response,App/RenewAIControl, andSsp/RenewAIControl;V1/get-file.
On an instance that uses Windows authentication, no token endpoint exists,
and a POST to /token answers with the envelope, saying that access-token
authentication is not configured.
Workflow actions that abort
When a workflow action is aborted while it runs and leaves at least one
message, the call reports success: false and copies only the last
message into errorText. The full message list stays in
responseObject.MessageList. If the last message is empty, or the abort
leaves no message, success stays true and only responseObject.Succeed
is false.
A refusal before the action runs - an unavailable action, an action of the
wrong kind, a missing object, the action's condition not being met, or an
unknown or mandatory field - comes back as an ordinary failure, with
responseObject set to null and no message list.
Errors
errorText is the message of the underlying error, passed through as
written. The API's error strings include unknown field, mandatory field,
unknown attachment area, invalid operation, action condition not satisfied,
object not found, inactive object, and impersonation not allowed for a given
method. The text is stable enough to log, but it is not a contract to parse.
When the error has an inner error, errorText contains both messages, the
inner one appended after a space.
An ordinary rule failure, such as an unmet action condition or an unknown
field, is returned to the caller in errorText but is not, by itself,
written to the API's log as a fatal error.
Date and time format
Date and date-time values in record fields, view columns, query filter values, and action-form fields are converted against the API instance's configured time zone, so every API client sees the same time zone whatever the technician's locale. The Admin Center shows this setting on the API instance's Timezone tab (see API Settings). When no time zone is set, the API uses the Windows time zone of the machine it runs on. In that case, the Timezone tab shows the time zone of the Admin Center's host, which can differ from the API's.
On input, a value is accepted in one of these forms:
- a date,
yyyy-mm-dd; - a date-time in UTC, ending in
Z; - a date-time with a
±hh:nnoffset.
A date-time value with no time zone is refused with
Invalid date/time format "<value>". A value with a time zone is shifted to
the configured time zone's local time before it is stored.
On output, a date-time field is written as yyyy-mm-ddThh:nn:ss±hh:nn: the
stored clock time followed by the offset the configured time zone has at
that moment, daylight saving time included. A date-only field is written as
yyyy-mm-dd with no offset.
The conversion assumes that stored values were written in the configured
time zone; with any other time zone, API values do not agree with the
database. If the configured time zone name is not a known Windows time zone,
nothing is converted: output carries +00:00, and input is stored as UTC.
When no time zone is set and the Windows time zone of the API's host cannot
be found in the machine's list of time zones, nothing is converted either.
The modification stamp an action form carries is written with no time zone
conversion.
Related topics
- Objects and Fields - which classes the API exposes and how to refer to fields, including HTML fields.
- API Settings - the API instance's settings in the Admin Center, including its time zone.