Overview

The Document Domain API is an enterprise-level API designed to enable internal and partner applications to integrate with Zurich AU's document management systems. This API operates with a defined message contract, facilitating interactions with multiple document host systems and requiring service requestors to adhere to the standard input for processing a document.

The following document systems are integrated with this API.

1. ICM - IBM Content Manager
2. ECMaaS - IBM Filenet Cloud
3. TRIM - Opentext TRIM
4. CCS - Computershare
5. SC - Smartcomm

This API provides the following interfaces,

1. Upload document - Inserts document content into the document management system along with document metadata.
2. Update Metadata - Update document metadata in the document management system.
3. Search document - search for documents based on specified criteria.
4. Download document - Retrieve document content from the document management system.
5. Generate document - Request the generation of a document.

How do I get access

New applications wishing to use the service can request access via the API Exchange. As part of the request, you will be asked for a cost centre and to select the service tier you require. Once the API Owner accepts your request you will be issued a Client ID and Secret which you can use to call the API. See Getting Start page for more information.

Obtaining Access

​
These steps assume you are already registered to use the Zurich Exchange. If you are not, please Register for an account in order to proceed. If this is your first time using one of our API's we suggest to go through our API Template page where you can find information on the basic concepts used throughout this API.
​

Request Access to a specific API

​
- Navigate to the API documentation and click the "Request Access" button above the API you wish to use.
​

​
- Select the "Instance" you wish to access - i.e. for a specific test environment or Production. Depending on the type of API you may have multiple options or just one available to you.
​

​
- Select the "Tier" that you wish to access. The tiers represent the policies that might apply to the API (i.e. Bronze may be restricted to n calls per minute). Tiering for most APIs is set as Bronze (1 API call per second - designed for testing and development), Silver (10 API calls per second - for larger volume scenarios) and Gold (100 API calls per second - use for Production scenarios). For some APIs these tiers may change and these will be detailed below in the Specific Configuration section.
​
- Click Next
​
- "Select an existing application" from the dropdown(if you have already requested access for other APIs), or "Create a new client application" and add a meaningful name. This Client Application will be linked to the key you'll be issued with for this API.
​
​

​
- Read the Terms & Conditions and check the box to accept these.
​
- Click "Request Access" to complete the request.
​
- Your access request will be assessed by the team and approved within 1 working day. You will receive an e-mail upon approval.
​

​## Overview
​
The API accepts HTTPS/TLS connections only in order to protect the integrity and confidentiality of any data transferred. HTTP connections are refused - plaintext communication is not supported.
​
As a further means to secure requests, this API, by default, uses Client Id/Secret headers.

​

​

Client ID/Secret Headers

​
Follow the pre-requisites steps found in the Home Page to register to this API and a selected environment.
​
Once you have registered and have been issued a Client Id/Secret pair you must supply these values as per below (cURL example):

--header 'client_id: ' \
--header 'client_secret: ' \

For further examples please see the console guidelines.

In case of an invalid token, a 401 HTTP Status Code with code authentication_error will be returned.
​

Overview

​
This API uses conventional HTTP response codes to indicate the success or failure of an API request.
​
In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required field was omitted). Codes in the 5xx range indicate an error with the server.

​

​

Error HTTP Status Code Summary

​
Note: This section should include an exhaustive list of error codes the API can return. The below is an example that should be adapted per API.
​
| Status Code | Description |
| ----------------------------| --------------------------------------------------------------------- |
| 400 Bad Request | The server could not understand the request due to invalid syntax |
| 401 Unauthorized | Invalid token. The server was unable to authenticate the user. |
| 415 Unsupported Media Type | The media format of the requested data is not supported by the server.|
| 500 Internal Server Error | An internal server error was observed. |
| 502 Bad Gateway | The server encountered received an invalid response from an inbound server it accessed while attempting to fulfil the request. |
| 503 Service Unavailable | The server was unable to handle the request due to a temporary overloading or maintenance of the server. |
​
Please refer to each individual resource and method endpoint definition for specific details on the possible status codes returned.

​

​

Error Response

​

Attributes

​
| Field Name | Description |
| --------------- | -------------------------------------------------------------------------------- |
| code | Pattern based scheme that identifies a specific and unique error condition. Typically human readable but more suited for machine processing. |
| message | Human readable description of the error that occurred that is not intended to be machine parseable. |
| correlationId | Provide ability to rapidly identify and trace distributed request processing. •|
| source | Optional. Describes the source of the error; used to indicate the error originated elsewhere or self-reference when error was generated internally or in direct consequence of downstream events. |
| source/name | Implementation provider defined name for the API, service or system.• |
| source/layer | Implementation provider defined name for the API, service or system.• |
| causes | Optional. Describes the source of the error; used to indicate the error originated elsewhere or self-reference when error was generated internally or in direct consequence of downstream events. |
| causes/code | Optional. Pattern based string that identifies a more fine grained error condition, which contributed to the general/parent error code above. •|
| causes/message | Mandatory. More specific information on the failure cause. •|
| causes/field | Optional. A JSON Pointer (RFC6901) that identifies the entity or entity attribute responsible for the more specific error code and message. ••|
| causes/source | Optional. See “source” object definition above •••|
​

Error Response Payload Examples

​
{ "code" : "RESOUCE_UPDATE_FAILED", "message" : "Cannot update User account groups", "correlationId": "3d9445ca-dd6c-4fe2-b93d-c23423f0d612", "source": { "name": "coupa_gfc", "layer": "DATA_SOURCE" }, "causes": [ { "code": FAILED_UPDATE_SECURITY_TYPE_DEFAULT, "message": "Failed to set security type to 1" } ] }

​

This API is available in the following environments: DEV
​
These can be accessed by requesting access to the specific instance during the Request Access process.
​
These environments have access to different data as listed below:
​
| Environment | Data Available |
| ----------------| ------------------------------------------------------------- |
| DEV | Mock data |
| SIT | Non-Production data |
| UAT / Pre-Prod | Copy of Production data |

Zurich is committed to continuously improving and expanding the services it provides its customers. All APIs developed by the group follow the Semantic Versioning specification.
​
Where possible, the Zurich Group will make changes to the API but not change the version number because the changes are not considered to be backward compatible. Such changes can be any of the following:
​

Addition of new resources
Addition of new non-mandatory request parameters of attributes
Addition of new data fields returned in the response
Change in the order of data fields returned by the API
​
There might be some instances in which breaking enhancements need to happen. In such circumstances, a new version is released not to break compatibility. Such enhancements include:
​
Inclusion or removal of mandatory parameters
Restructuring of the API interface
​
Upon the release of a new version, applications can continue using the old version, allowing the consumer to assess the changes needed. Release notes with all the changes will be provided with every new version, describing all the changes in detail.
​
Upon upgrading, consumers are encouraged to perform regression testing against the new version before upgrading to the new API version in production.

Of particular importance is the requirement for all consumers of the API to ensure that the content that they send via this has been assessed for compliance with Zurich's information security policies and are in compliance with your local data laws. This is a responsibility of the API Consumer and not the Service Provider.
​
In addition you may not:
​
- modify, obscure, reverse engineer, circumvent, or disable any element of the API or its access control features
- disclose, share, or transfer Your access credentials to any third party
- transmit any viruses, worms, defects, Trojan horses, or any other malware through Your Application or use of the API
- use robots, spiders, crawlers, scraping or other similar technology to obtain any information beyond what Zurich provides to You under these Terms/
- use the API in a manner that exceeds reasonable request volume, constitutes excessive or abusive usage or otherwise fails to comply or is inconsistent with any part of the Zurich API documentation.
- infringe, misuse, or claim ownership of Zurich intellectual property or intellectual property rights therein
- use it with an Application that is offensive, abusive, libelous, harassing, threatening, discriminatory, vulgar, pornographic, unethical, unlawful, or otherwise inappropriate as determined by Zurich in its sole discretion
- assign or transfer Your rights or obligations under this Agreement
- Further terms of Service are provided in separate Terms & conditions which are presented when registering for the API.

Contact

​
Contact the zurich.mulesoft@zurich.com.au for more information or support.
​