Response Formats

Responses are always in JSON format.

Response Headers

Responses may include some of the following response headers:

Header	Value	Comments
Content-Type	application/vnd.ib.api-v?+json	Where ? is the version number. See versions for specific versions supported.
Authorization	An authorization token for the user.	Depending on the age of the authorization token used in the request this may represent a refreshed token. If this value is present and differs from the token used in the request then this refreshed token should be used for future requests.
X-Language	The language used for the response.	This is the language submitted with the request or the language configured for the current user.
X-Encryption-Key-Tag	The key tag or key id for the encryption key utilized for response encryption.	This is only included when the api endpoint is configured for response encryption.
X-Api-Server	The name of the api server responding to the API request.	This is only included when the request includes a X-Trace=True header.
X-Data-Server	The name of the data server responding to the API request.	This is only included when the request includes a X-Trace=True header.
X-Data-Store	The name of the data store utilized for this API request.	This is only included when the request includes a X-Trace=True header.
X-Core-Version	The core version number of the back end data schema and services.	This is only included when the request includes a X-Trace=True header.
X-Auth-User	The name of the authorized user based on the authorization token or api key provided.	This is only included when the request includes a X-Trace=True header.

Response Body Format

All API responses are in JSON format and share some common response format elements as shown in this example:

{
    "Success": true,
    "ResultCode": 0,
    "ResultText": "Success",
    "Message": "Success",
    "Scope": {
        "TotalResults": 1,
        "IncludedResults": 1,
        "PageNumber": 1,
        "PageSize": 1,
        "PageCount": 1,
        "Sort": "",
        "FilterId": null,
        "Filter": "",
        "Q": "",
        "Expand": ""
    },
    "Data": null,
    "Meta": null,
    "Links": [
    {
      "Rel": "self",
      "Url": "http://...",
      "Method": "GET"
    }
    ],
    "Errors": [
    {
      "ResultCode": 0,
      "Type": "",
      "Subtype": "",
      "Reference": "",
      "Message": "",
      "Details": "",
      "Warning": false
    }
    ],
    "TimeStamp": "2014-05-28T12:30:07.2447Z",
    "Trace": [
    ""
    ]
}

The common response properties include:

• Success - A boolean value indicating if the request was successful or not.
• ResultCode - The result code of the request. This provides additional insight into failed requests.
• ResultText - The result text that provides information about the result of the request.
• Message - A message detailing the result of the request.
• Scope - An object that includes scope information for requests that call for a collection of data results.
  • TotalResults - The total number of results available in response to the request.
  • IncludedResults - The number of results included in this response.
  • PageNumber - The page number of this response.
  • PageSize - The page size of the response.
  • PageCount - The number of pages available with results.
  • Sort - The sort expression used for retrieving the results.
  • FilterId - The filter id of a saved filter used for retrieving the results.
  • Filter - The filter used for retrieving the results.
  • Q - Any free form filter text used for retrieving the results.
  • Expand - A comma delimited list of expanded objects in the results (if any).
• Data - The result data for the request. Requests that do not call for data to be returned or which failed may have null or an empty object for this property.
• Meta - Meta data about the result data. Typically, meta data needs to be enabled via the X-Meta-Data request header. Even then, not all results will include meta data and the contents will differ for different result types. Examples of things included with meta data:
  • Options - For results with data properties that have a list of accepted values the possible values that are accepted will be enumerated here.
  • Attributes - For results with a data object that has attributes defined this documents the attribute properties.
  • Timestamps - For results that support reporting of timestamps this object holds keys that represent various steps in the process with values that represent the timestamp when each step occurred. If not otherwise specified in the name of the key the timestamp is when the step started.
  • Durations - For results that support reporting of durations this object holds keys that represent various steps in the process with values that represent the duration in milliseconds that the step took to complete.
  • VersionConflictInformation - For edit results that failed with result code 1611 (ChangedByAnotherUser) this property will include version conflict information if any was available.
• Links - A collection of links related to this response.
  • Rel - The relationship of the link to the response. For example: Self, First, Last, Next, Prev.
  • Url - The url of the link.
  • Method - The http method to use with the link.
• Errors - A collection of errors related to this response. Note that if the result code for the response indicates partial success this error collection may include not only errors but also information about each parts of the request so it is clear which parts of the request were successful and which failed.
  • ResultCode - The result code related to this type of error.
  • Type - The type of error.
  • Subtype - The subtype of error.
  • Reference - The reference for the error.
  • Message - The error message.
  • Details - Any details that are available for the error.
  • Warning - If true the error object represents a warning.
• TimeStamp - The timestamp of the response.
• Trace - A collection of strings that provides trace or debug information about the response.