Request Formats

Since the API is based on REST principles, it's very easy to write and test applications. You can use pretty much any HTTP client in any programming language to interact with the API.

Request Headers

Since the API is stateless each API call requires authentication information to be included in the form of either an Authorization header or X-Auth-Key header. All other headers are optional but may be helpful in various scenarios:

Header	Value	Comments
Accept	application/vnd.ib.api-v?+json	Where ? is the version number. See versions for specific versions supported.
Content-Type	application/vnd.ib.api-v?+json	Used when posting data. Where ? is the version number. See versions for specific versions supported.
X-Api-Version	API Version Number (e.g. 1)	The API version number to use. See versions for specific versions supported.
Authorization	Bearer <token>	Token provided by the login API endpoint or included in response to another API endpoint request as either a refreshed token or token to use as replacement for a different authentication mechanism like X-Auth-External-Token. Note that either Authorization, X-Auth-Key, or X-Auth-External-Token header is required as part of each request except for the login API request which is used to retrieve the authorization token.
X-Auth-Key	Your API Key	The API Key provided for API access. Either Authorization, X-Auth-Key, or X-Auth-External-Token header is required as part of each request except for the login API request which is used to retrieve the authorization token.
X-Auth-External-Token	<external token>	An external authorization token provided by a partner system to be used for external authorization of the user. Either Authorization, X-Auth-Key, or X-Auth-External-Token header is required as part of each request except for the login API request which is used to retrieve the authorization token.
X-Language	Language	This is the language to use when the response includes values that can be translated. If not specified, the user configured language preference will be used.
X-Meta-Data	A CSV list of meta data to include in the response data's meta object.	Possible values in the csv include: Options - If the result data object has properties that have a list of accepted values then the accepted values are documented in the meta data. Attributes - If the result data object has attributes defined then the attribute properties are documented in the meta data. Timestamps - If the api endpoint supports reporting of timestamps then the timestamps for various steps are documented in the meta data. Durations - If the api endpoint supports reporting of durations then the durations (in milliseconds) for various steps are documented in the meta data. All - All supported meta data is included. True - Legacy value that is the equivalent of specifying All. False - Legacy value that is the equivalent of not specifying anything.
X-Trace	TRUE or FALSE	When true the response will include additional trace information that can be used for debug purposes. The trace information is not documented and is largely only helpful when needing to communicate an issue to technical support.
X-Overwrite-Changes	TRUE or FALSE	Some API PUT methods may get a failed response that someone else already edited object and, therefore, the PUT was rejected because it would have resulted in another user's edits being lost. The best action to take is for the client to GET the updated object and then merge in the current user's edits and to continue. However, if that is not possible or if for other reasons you want to overwrite the other user's edits then this header can be set to true and the PUT method retried. Note that this will result in data loss and is rarely recommended as the best course of action.
X-HTTP-Response-Override	TRUE or FALSE	Can be used if HTTP library being utilized only accepts 200 OK response for processing. Some clients intercept any non-OK response which prevents normal processing of non-OK responses from the API. Setting this header to TRUE will result in all API responses having a 200 OK response from the server. The client should then inspect the result code to determine if the API call was successful or not.
X-HTTP-Method-Override	PUT, DELETE, PATCH, or MERGE	Can be used if HTTP library being utilized only supports GET and POST or does not support custom verbs (e.g. MERGE). If that is the case use a POST where PUT, DELETE, PATCH, or MERGE (custom verb) are called for but include this header to indicate if a PUT, DELETE, PATCH or MERGE was requested.
X-Local-Device-Id	Device Id	This is a short guid like string that uniquely identifies a user or device but does so in an anonymous way. The API does not know anything about the user or device represented by this id but can reasonably expect that the id represents the same user or device for purposes of collecting anonymous information like anonymously provided feedback. For certain anonymous operations like leaving feedback knowing a user or device id allows proper collection of anonymous feedback for many users who share the same public ip address as is typical in a multi-user environment. For example, all users in a home or office typically use a technology like NAT which causes all users in that environment to share a single public ip address. As a result, all users sharing that public ip address are limited to sharing a single feedback. By knowing a user or device id the anonymous feedback mechanism can allow each combination of private/device id and public ip address to have their own feedback.
X-Response-Properties	A CSV list of response properties to include in the response data in jpath format (e.g. Response.ResultText, AssociationId, Cargo.TransactionId).	This is an optional (and typically omitted) comma separated list of properties that should be included in the response data property. Note that: It has no impact on the non-data portions of the response object (e.g. errors, links, etc.). When omitted the standard set of response properties are included with the data. With rare exception this can only be used to identify properties from the existing standard response data and not to add additional properties not included in the standard response data. To rename a property separate the source and target names with a colon (e.g. Cargo.TransactionId:TransId). In bulk processing scenarios where multiple objects can be submitted each corresponding object included in the response will typically also be able to access the common response object properties by referencing them with a "Response." prefix in order to provide response values like success, result code, etc. for each object (e.g. Response.ResultCode).
X-Response-Encryption-Properties	A CSV list of response properties to encrypt in jpath format (e.g. ContactInformation.FirstName, ContactInformation.LastName, ContactInformation.Name, ContactInformation.Phone, ContactInformation.Email, Packages[*].PaymentTransactionOrderReference)	This is a comma separated list of properties that should be encrypted in the response using the encryption information configured. Part of the configuration can include a list of properties to encrypt. Any properties specified here are merged with those configured properties (if any). If nothing is specified here then only the configured properties will be encrypted. Currently only string data type properties can be encrypted. Note that most servers only allow 4K-8K of HTTP headers. Since the API exclusively uses HTTPS there is no need to encrypt a large number of properties. This should primarily be used for PII that should be encrypted when appearing in log files, etc. Note that only limited API endpoints support this feature.
X-Encryption-Key-Tag	Encryption Key Tag (e.g. 7qw-1ej2kx4v7e5lb-4s8i49d5iq9l)	This is the encryption key tag of the encryption key used to encrypt some of the properties of this API call. Use the get encryption key api endpoint to retrieve an encryption key and tag.
X-Encrypted-Properties	A CSV list of encrypted properties in jpath format (e.g. Payment.CreditCard.CreditCardNumber, Payment.CreditCard.CardId, Packages[*].Payment.CreditCard.CreditCardNumber, Packages[*].Payment.CreditCard.CardId)	This is a comma separated list of properties that were encrypted using the encryption key represented by X-Encryption-Key-Tag. Do not encrypt data without specifying those properties in this header and providing a X-Encryption-Key-Tag header. Currently only string data type properties can be encrypted. Note that most servers only allow 4K-8K of HTTP headers. Since the API exclusively uses HTTPS there is no need to encrypt a large number of properties. This should primarily be used for passing data that must be encrypted when at rest on local systems for compliance with industry security standards (e.g. PCI, HIPAA, etc.).