Integrations

Integrations extend ALX system features. To function, they need to be configured and managed by the system users with required permissions.

Permissions

Permission	Manageable via Roles	Description
list	true	Allows list integration configurations.
view	true	Allows view details of integration configurations.
create	true	Allows create integration configurations.
edit	true	Allows edit integration configurations.
delete	true	Allows delete integration configurations.

Permissions for integrations can be checked by:

Context	Endpoint	Location	Available perms
Global scope	`GET /api/users/permissions/`	`integrations`	`list`, `view`, `create`, `edit`, `delete`
Specific integration configuration	`GET /api/integrations/{uuid}/`	`_meta.permissions`	`list`, `view`, `create`, `edit`, `delete`

References

Integrations - technical design

POST /api/integrations/

Creates integration configuration. For different integration types there can be different validation rules.

Permissions

Requires authentication and integrations.create permission.

Request

Body parameters

Important

Schema is based on integration type.

Please check details.schema_by_type in OPTIONS /api/integrations/.

Key	Type	Notes
type	enum
name	string
description	string
is_enabled	bool
authentication_object	enum	Please check "details.schema_by_type" in OPTIONS /api/integrations/
object_class	enum	Please check "details.schema_by_type" in OPTIONS /api/integrations/

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

POST /api/integrations/ 

{
  "type": <enum>,
  "name": <string>,
  "description": <string>,
  "is_enabled": <bool>,
  "authentication_object": <enum>,
  "object_class": <enum>
}

Validations

Below there are validation rules common to all types of integrations:

name
- Ensure this field has no more than 100 characters.
- This field is required.
- This field may not be blank.
- This field may not be null.
- This field must be unique.
description
- This field may not be null.
- Ensure this field has no more than 500 characters.
is_enabled
- This field may not be null.

Some fields have custom validations based on integration type. Please check details.schema_by_type in OPTIONS /api/integrations/.

Response

Key	Type	Notes
uuid	uuid	Automatically generated by the backend.
type	enum
name	string
description	string
is_enabled	bool	Default value is `false`.
authentication_object	enum
object_class	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 201 Created
Response body schema

json

{
  "uuid": <uuid>,
  "type": <enum>,
  "name": <string>,
  "description": <string>,
  "is_enabled": <bool>,
  "authentication_object": <enum>,
  "object_class": <enum>,
  ... // attributes specific for type
  "created_at": <datetime>,
  "created_by": <user>,
  "modified_at": <datetime>,
  "modified_by": <user>
  "_meta": {
    "labels": {
      "type": <string>,
      "authentication_object": <string>,
      "object_class": <string>,
      ... // attributes specific for type
    },
    "permissions": {
      "list": <bool>,
      "view": <bool>,
      "create": <bool>,
      "edit": <bool>,
      "delete": <bool>
    }
  }
}

Errors

Cause	Response code	Message
"type" is missing	400 Bad Request	"type": ["This field is required."]
"{value}" for "type" is out of choices	400 Bad Request	"type": ["\"{value}\" is not a valid choice."]
"name" is missing	400 Bad Request	"name": ["This field is required."]
"name" is empty string	400 Bad Request	"name": ["This field may not be blank."]
"name" is null	400 Bad Request	"name": ["This field may not be null."]
"name" has > 100 chars	400 Bad Request	"name": ["Ensure this field has no more than 100 characters."]
"name" is not unique	400 Bad Request	"name": ["This field must be unique."]
"description" is null	400 Bad Request	"description": ["This field may not be null."]
"description" has > 500 chars	400 Bad Request	"description": ["Ensure this field has no more than 500 characters."]
"is_enabled" is null	400 Bad Request	"is_enabled": ["This field may not be null."]
"authentication_object" is not int	400 Bad Request	"authentication_object": ["Incorrect type. Expected pk value, received {type}."]
Authentication object with "authentication_object" does not exist	400 Bad Request	"authentication_object": ["Invalid pk \"{value}\" - AuthenticationObjectData does not exist."]
"object_class" is not int	400 Bad Request	"object_class": ["Incorrect type. Expected pk value, received {type}."]
Object class with "object_class" does not exist	400 Bad Request	"object_class": ["Invalid pk \"{value}\" - ObjectClass does not exist."]
Max 100 Integration configurations exceeded	400 Bad Request	"detail": "Limit of 100 Integrations has been exceeded.", "error_code": "ERR_LIMIT_EXCEEDED"
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

iManage

Below sections for iManage integration type extend the above.

Request

Body parameters

Additional body parameters:

Key	Type	Notes
folder	string
object_class_field	enum	Please check "details.schema_by_type" in OPTIONS /api/integrations/
dedupe	bool

Schema

json

POST /api/integrations/ 

{
  ... // common attributes for all types
  "folder": <string>,
  "object_class_field": <enum>,
  "dedupe": <bool>
}

Validations

Below there are validation rules specific for iManage integration type:

folder
- Ensure this field has no more than 255 characters.
- This field is required.
- This field may not be blank.
- This field may not be null.
dedupe
- This field may not be null.

Response

Additional response schema:

Key	Type	Notes
folder	string
dedupe	bool	Default value is `false`.
object_class_field	enum

Successful status 201 Created
Response body schema

json

{
  ... // common attributes for all types
  "folder": <string>,
  "object_class_field": <enum>,
  "dedupe": <bool>
  ... // common attributes for all types
  "_meta": {
    "labels": {
      ... // common attributes for all types
      "object_class_field": <string>
    },
    ...
  }
}

Errors

Additional errors:

Cause	Response code	Message
"folder" is missing	400 Bad Request	"folder": ["This field is required."]
"folder" is empty string	400 Bad Request	"folder": ["This field may not be blank."]
"folder" is null	400 Bad Request	"folder": ["This field may not be null."]
"folder" has > 255 chars	400 Bad Request	"folder": ["Ensure this field has no more than 255 characters."]
"object_class_field" is not int	400 Bad Request	"object_class_field": ["Incorrect type. Expected pk value, received {type}."]
Object class field with "object_class_field" does not exist	400 Bad Request	"object_class_field": ["Invalid pk \"{value}\" - ObjectClassField does not exist."]
"dedupe" is null	400 Bad Request	"dedupe": ["This field may not be null."]

GET /api/integrations/

Returns list of integration configurations.

Permissions

Requires authentication and integrations.list permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/integrations/

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
uuid	uuid
type	enum
name	string
description	string
is_enabled	bool
authentication_object	enum
object_class	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema

json

{
  "limit": <int>,
  "offset": <int>,
  "filtered_count": <int>,
  "total_count": <int>,
  "next": <str>,
  "previous": <str>,
  "results": [
    {
      "uuid": <uuid>,
      "type": <enum>,
      "name": <string>,
      "description": <string>,
      "authentication_object": <enum>,
      "object_class": <enum>,
      "created_at": <datetime>,
      "created_by": <user>,
      "modified_at": <datetime>,
      "modified_by": <user>,
      "_meta": {
        "labels": {
          "type": <string>,
          "authentication_object": <string>,
          "object_class": <string>
        },
        "permissions": {
            "list": <bool>,
            "view": <bool>,
            "create": <bool>,
            "edit": <bool>,
            "delete": <bool>
        }
      }
    }
  ]
}

Sorting

Parameter	Example	Notes
name	/api/integrations/?ordering=name	Ascending
name	/api/integrations/?ordering=-name	Descending (-)
created_at	/api/integrations/?ordering=created_at	Ascending
created_at	/api/integrations/?ordering=-created_at	Descending (-)
modified_at	/api/integrations/?ordering=modified_at	Ascending
modified_at	/api/integrations/?ordering=-modified_at	Descending (-)

Filtering

Please check ALX API standards for predicates available per type.

Parameter	Type
uuid	uuid
type	enum
name	string
is_enabled	bool
authentication_object	enum
object_class	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user

Errors

Error	Response code	Message
Wrong ordering value	400 Bad Request	"ordering": ["Select a valid choice. {value} is not one of the available choices."]

GET /api/integrations/`uuid`/

Returns single integration configuration by uuid.

Permissions

Requires authentication and integrations.view permission.

Request

URL parameters

Key	Type	Notes
uuid	uuid

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/integrations/`uuid`/

Response

Important

Schema is based on integration type.

Please check details.schema_by_type in OPTIONS /api/integrations/.

Key	Type	Notes
uuid	uuid
type	enum
name	string
description	string
is_enabled	bool
authentication_object	enum
object_class	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
  "uuid": <uuid>,
  "type": <enum>,
  "name": <string>,
  "description": <string>,
  "is_enabled": <bool>,
  "authentication_object": <enum>,
  "object_class": <enum>,
  ... // attributes specific for type
  "created_at": <datetime>,
  "created_by": <user>,
  "modified_at": <datetime>,
  "modified_by": <user>,
  "_meta": {
    "labels": {
      "type": <string>,
      "authentication_object": <string>,
      "object_class": <string>,
      ... // attributes specific for type
    },
    "permissions": {
      "list": <bool>,
      "view": <bool>,
      "create": <bool>,
      "edit": <bool>,
      "delete": <bool>
    }
  }
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Integration configuration with "uuid" does not exist	404 Not Found	"detail": "Not found."

iManage

Below sections for iManage integration type extend the above.

Response

Additional response schema:

Key	Type	Notes
folder	string
dedupe	bool
object_class_field	enum

Successful status 201 Created
Response body schema

json

{
  ... // common attributes for all types
  "folder": <string>,
  "object_class_field": <enum>,
  "dedupe": <bool>
  ... // common attributes for all types
  "_meta": {
    "labels": {
      ... // common attributes for all types
      "object_class_field": <string>
    },
    ...
  }
}

PATCH /api/integrations/`uuid`/

Updates single integration configuration.

Permissions

Requires authentication and integrations.edit permission.

Request

URL parameters

Key	Type	Notes
uuid	uuid

Body parameters

Important

type cannot be changed.

Important

Schema is based on integration type.

Please check details.schema_by_type in OPTIONS /api/integrations/.

Key	Type	Notes
name	string
description	string
is_enabled	bool
authentication_object	enum
object_class	enum

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

PATCH /api/integrations/`uuid`/

{
  "name": <string>,
  "description": <string>,
  "is_enabled": <bool>,
  "authentication_object": <enum>,
  "object_class": <enum>
}

Response

Key	Type	Notes
uuid	uuid
type	enum
name	string
description	string
is_enabled	bool
authentication_object	enum
object_class	enum
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.labels	Object	Object containing labels for attributes.
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
  "uuid": <uuid>,
  "type": <enum>,
  "name": <string>,
  "description": <string>,
  "is_enabled": <bool>,
  "authentication_object": <enum>,
  "object_class": <enum>,
  ... // attributes specific for type
  "created_at": <datetime>,
  "created_by": <user>,
  "modified_at": <datetime>,
  "modified_by": <user>,
  "_meta": {
    "labels": {
      "type": <string>,
      "authentication_object": <string>,
      "object_class": <string>,
      ... // attributes specific for type
    },
    "permissions": {
      "list": <bool>,
      "view": <bool>,
      "create": <bool>,
      "edit": <bool>,
      "delete": <bool>
    }
  }
}

Errors

Cause	Response code	Message
"name" is empty string	400 Bad Request	"name": ["This field may not be blank."]
"name" is null	400 Bad Request	"name": ["This field may not be null."]
"name" has > 100 chars	400 Bad Request	"name": ["Ensure this field has no more than 100 characters."]
"name" is not unique	400 Bad Request	"name": ["This field must be unique."]
"description" is null	400 Bad Request	"description": ["This field may not be null."]
"description" has > 500 chars	400 Bad Request	"description": ["Ensure this field has no more than 500 characters."]
"is_enabled" is null	400 Bad Request	"is_enabled": ["This field may not be null."]
"authentication_object" is not int	400 Bad Request	"authentication_object": ["Incorrect type. Expected pk value, received {type}."]
Authentication object with "authentication_object" does not exist	400 Bad Request	"authentication_object": ["Invalid pk \"{value}\" - AuthenticationObjectData does not exist."]
"object_class" is not int	400 Bad Request	"object_class": ["Incorrect type. Expected pk value, received {type}."]
Object class with "object_class" does not exist	400 Bad Request	"object_class": ["Invalid pk \"{value}\" - ObjectClass does not exist."]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Integration configuration with "uuid" does not exist	404 Not Found	"detail": "Not found."

iManage

Below sections for iManage integration type extend the above.

Request

Body parameters

Additional body parameters:

Key	Type	Notes
folder	string
object_class_field	enum	Please check "details.schema_by_type" in OPTIONS /api/integrations/
dedupe	bool

Schema

json

PATCH /api/integrations/`uuid`/

{
  ... // common attributes for all types
  "folder": <string>,
  "object_class_field": <enum>,
  "dedupe": <bool>
}

Validations

Below there are validation rules specific for iManage integration type:

folder
- Ensure this field has no more than 255 characters.
- This field may not be blank.
- This field may not be null.
dedupe
- This field may not be null.

Response

Additional response schema:

Key	Type	Notes
folder	string
dedupe	bool	Default value is `false`.
object_class_field	enum

Successful status 200 OK
Response body schema

json

{
  ... // common attributes for all types
  "folder": <string>,
  "object_class_field": <enum>,
  "dedupe": <bool>
  ... // common attributes for all types
  "_meta": {
    "labels": {
      ... // common attributes for all types
      "object_class_field": <string>
    },
    ...
  }
}

Errors

Additional errors:

Cause	Response code	Message
"folder" is empty string	400 Bad Request	"folder": ["This field may not be blank."]
"folder" is null	400 Bad Request	"folder": ["This field may not be null."]
"folder" has > 255 chars	400 Bad Request	"folder": ["Ensure this field has no more than 255 characters."]
"object_class_field" is not int	400 Bad Request	"object_class_field": ["Incorrect type. Expected pk value, received {type}."]
Object class field with "object_class_field" does not exist	400 Bad Request	"object_class_field": ["Invalid pk \"{value}\" - ObjectClassField does not exist."]
"dedupe" is null	400 Bad Request	"dedupe": ["This field may not be null."]

DELETE /api/integrations/`uuid`/

Deletes single integrations configuration.

Permissions

Requires authentication and integrations.delete permission.

Request

URL parameters

Key	Type	Notes
uuid	uuid

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

DELETE /api/integrations/`uuid`/

Response

Successful status 204 No Content

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Integration configuration with "uuid" does not exist	404 Not Found	"detail": "Not found."

OPTIONS /api/integrations/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

OPTIONS /api/integrations/

Response

Successful status 200 OK
Response body:

json

{
  "list": {
    "columns": [
      {
        "alias": "uuid",
        "type": "uuid",
        "predicates": [
          "exact"
        ],
        "sort_ok": false
      },     
      {
        "alias": "type",
        "type": "enum",
        "predicates": [
          "exact,
          "in"
        ],
        "sort_ok": false
      },
      {
        "alias": "name",
        "type": "string",
        "predicates": [
          "exact",
          "iexact",
          "contains",
          "icontains",
          "startswith",
          "istartswith",
          "endswith",
          "iendswith"
        ],
        "sort_ok": true
      },
      {
        "alias": "is_enabled",
        "type": "bool",
        "predicates": [
          "exact
        ],
        "sort_ok": false
      },
      {
        "alias": "authentication_object",
        "type": "enum",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": true
      },
      {
        "alias": "object_class",
        "type": "enum",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": true
      },
      {
        "alias": "created_at",
        "type": "datetime",
        "predicates": [
          "exact",
          "gt",
          "gte",
          "lt",
          "lte",
          "range"
        ],
        "sort_ok": true
      },
      {
        "alias": "created_by",
        "type": "user",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": false,
        "autocomplete": "/api/users/autocomplete/?text__icontains="
      },
      {
        "alias": "modified_at",
        "type": "datetime",
        "predicates": [
          "exact",
          "gt",
          "gte",
          "lt",
          "lte",
          "range"
        ],
        "sort_ok": true
      },
      {
        "alias": "modified_by",
        "type": "user",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": false,
        "autocomplete": "/api/users/autocomplete/?text__icontains="
      }
    ]
  },
  "details": {
    "schema": [
      {
        "alias": "type",
        "type": "enum",
        "required": true,
        "values": [
          {
              "value": 1,
              "text": "iManage"
          }
        ]
      },
      {
        "alias": "name",
        "type": "string",
        "required": true,
        "validators": [
          {
              "type": "min_length",
              "length": 1
          },
          {
              "type": "max_length",
              "length": 100
          }
        ]
      },
      {
        "alias": "description",
        "type": "string",
        "required": false
      },
      {
        "alias": "is_enabled",
        "type": "bool",
        "required": false
      }
    ],
    "schema_by_type": [
      {
        "type": 1,
        "schema": [
          {
            "alias": "authentication_object",
            "type": "enum",
            "required": true,
            "autocomplete": "/api/authentication-objects/autocomplete/?text__icontains="
          },
          {
            "alias": "object_class",
            "type": "enum",
            "required": true,
            "autocomplete": "/api/object-classes/autocomplete/?text__icontains="
          },
          {
            "alias": "object_class_field",
            "type": "enum",
            "required": true,
            "autocomplete": "/api/object-classes/{object_class}/fields/autocomplete/?text__icontains="
          },
          {
            "alias": "folder",
            "type": "string",
            "required": true,
            "validators": [
              {
                  "type": "min_length",
                  "length": 1
              },
              {
                  "type": "max_length",
                  "length": 255
              }
            ]
          }
        ]
      }
    ]
  },
  "restrictions": {
    "limit_items": 100
  }
}

POST /api/integrations/test/

Tests integration configuration. For different integration types there can be different validation rules.

Permissions

Requires authentication and integrations.create permission.

Request

Body parameters

Important

Schema is based on integration type.

Headers

Content-Type: application/json
Authorization: JWT access_token

Important

Please check next sections for specific integration types.

Response

Key	Type	Notes
status	string
errors	Object

Successful status 200 OK
Response body schema

json

{
  "status": <string>,
  "errors": <Object>
}

Possible status values:

"ok"
"error"

Example of successful response when status is ok:

json

{
  "status": "ok",
  "errors": {}
}

Example of successful response when status is error:

json

{
  "status": "error",
  "errors": {
    "non_field_errors": ["Authentication failed."]
  }
}

Errors

Cause	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

iManage

Below sections for iManage integration type extend the above.

Request

Body parameters

Key	Type	Notes
authentication_object	enum	Please check "details.schema_by_type" in OPTIONS /api/integrations/

Schema

json

POST /api/integrations/test/ 

{
  "authentication_object": <enum>
}

Response

Important

Please check previous sections for common behaviour.

Errors

Cause	Response code	Message
"authentication_object" is not int	400 Bad Request	"authentication_object": ["Incorrect type. Expected pk value, received {type}."]
Authentication object with "authentication_object" does not exist	400 Bad Request	"authentication_object": ["Invalid pk \"{value}\" - AuthenticationObjectData does not exist."]

OPTIONS /api/administration/smtp-settings/

Permissions

Requires authentication only.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

OPTIONS /api/administration/smtp-settings/

Response

Successful status 200 OK
Response body:

json

{
    "details": {
        "schema": [
            {
                "alias": "password",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 128
                    }
                ]
            },
            {
                "alias": "host",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 63
                    }
                ]
            },
            {
                "alias": "port",
                "required": true,
                "type": "int"
            },
            {
                "alias": "tls",
                "type": "bool"
            },
            {
                "alias": "username",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 254
                    }
                ]
            },
            {
                "alias": "from_email",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "email"
                    },
                    {
                        "type": "max_length",
                        "length": 254
                    }
                ]
            },
            {
                "alias": "failure_email",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 255
                    },
                    {
                        "type": "max_value",
                        "length": 10
                    }
                ]
            },
            {
                "alias": "authorization_method",
                "type": "enum",
                "required": false,
                "values": [
                    {
                        "value": "username_and_password",
                        "text": "Username and Password"
                    },
                    {
                        "value": "microsoft_client_credentials",
                        "text": "Microsoft Client Credentials"
                    }
                ],
                "schema_by_authorization_method": [
                    {
                        "authorization_method": "username_and_password",
                        "schema": [
                            {
                                "alias": "password",
                                "type": "string",
                                "required": true,
                                "validators": [
                                    {
                                        "type": "max_length",
                                        "length": 128
                                    }
                                ]
                            }
                        ]
                    },
                    {
                        "authorization_method": "microsoft_client_credentials",
                        "schema": [
                            {
                                "alias": "authentication_object",
                                "type": "enum",
                                "required": true,
                                "autocomplete": "/api/authentication-objects/?provider=microsoft_client_credentials"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

GET /api/administration/smtp-settings/

Permissions

Requires authentication and outbound_mail_setup.view permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/administration/smtp-settings/

Response

Key	Type	Notes
username	string
port	int
tls	bool
host	string
from_email	string
failure_email	string
authorization_method	enum	Values: username_and_password, microsoft_client_credentials
authentication_object	int

Successful status 200 OK
Response body schema:

json

{ 
 "username": "ticket.branch.mailserver@autologyx.net", 
 "port": 10587, 
 "tls": true, 
 "host": "clust.mx.nwc.xxx", 
 "from_email": "example1@email.com", 
 "failure_email": "example2@email.com, example9@email.com, example10@email.com, example11@email.com",
 "authorization_method": "username_and_password", 
 "authentication_object": null
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

PATCH /api/administration/smtp-settings/

Permissions

Requires authentication and outbound_mail_setup.edit permission.

Request

Key	Type	Notes
password	string
username	string
port	int
tls	bool
host	string
from_email	string
failure_email	string
authorization_method	enum	Values: username_and_password, microsoft_client_credentials
authentication_object	int	Required when `authorization_method` is `microsoft_client_credentials`

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

PATCH /api/administration/smtp-settings/ 

{ 
   "password": "Passwod", 
   "username": "ticket.branch.mailserver@autologyx.net", 
   "port": 10587, 
   "tls": true, 
   "host": "clust.mx.nwc.xxx", 
   "from_email": "example1@email.com", 
   "failure_email": "example6@email.com, example7@email.com",
   "authorization_method": "microsoft_client_credentials",
   "authentication_object": 1
}

Response

Key	Type	Notes
username	string
port	int
tls	bool
host	string
from_email	string
failure_email	string
authorization_method	string
authentication_object	int

Successful status 200 OK
Response body schema:

json

{ 
 "username": "ticket.branch.mailserver@autologyx.net", 
 "port": 10587, 
 "tls": true, 
 "host": "clust.mx.nwc.xxx", 
 "from_email": "example1@email.com", 
 "failure_email": "example6@email.com, example7@email.com",
 "authorization_method": "microsoft_client_credentials",
 "authentication_object": 1
}

Errors

Cause	Response code	Message
"username" is empty string	400 Bad Request	"username": ["This field may not be blank."]
"username" is null	400 Bad Request	"username": ["This field may not be null."]
"username" has > 254 chars	400 Bad Request	"username": ["Ensure this field has no more than 254 characters."]
"password" is empty string	400 Bad Request	"password": ["This field may not be blank."]
"password" is null	400 Bad Request	"password": ["This field may not be null."]
"password" has > 128 chars	400 Bad Request	"password": ["Ensure this field has no more than 128 characters."]
"port" is required	400 Bad Request	"port": ["This field is required."]
"port" is invalid	400 Bad Request	"port": ["A valid integer is required."]
"port" < 0	400 Bad Request	"port": ["Ensure this value is greater than or equal to 0."]
"port" > 65535	400 Bad Request	"port": ["Ensure this value is less than or equal to 65535."]
"tls" invalid	400 Bad Request	"tls": ["Must be a valid boolean."]
"host" is required	400 Bad Request	"host": ["This field is required."]
"host" has > 63 chars	400 Bad Request	"host": ["Ensure this field has no more than 63 characters."]
"from_email" has > 254 chars	400 Bad Request	"from_email": ["Ensure this field has no more than 254 characters."]
"failure_email" has > 255 chars	400 Bad Request	"failure_email": ["Ensure this field has no more than 255 characters."]
"failure_email" has > 10 comma separated items	400 Bad Request	"failure_email": ["Up to 10 items allowed."]
"authorization_method" has invalid value	400 Bad Request	"authorization_method": ["{value} is not a valid choice."]
"authentication_object" is absent when "authorization_method" is "microsoft_client_credentials"	400 Bad Request	"authentication_object": ["This field is required."]
"authentication_object" has the wrong provider type for a given "authorization_method"	400 Bad Request	"authentication_object": ["{value} is not a valid choice."]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Integration configuration with "uuid" does not exist	404 Not Found	"detail": "Not found."

POST /api/administration/smtp-settings/test/

Permissions

Requires authentication and outbound_mail_setup.edit permission.

Request

Key	Type	Notes
password	string
username	string
port	int
tls	bool
host	string

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

POST /api/administration/smtp-settings/test/ 

{ 
   "password": "Passwod", 
   "username": "ticket.branch.mailserver@autologyx.net", 
   "port": 10587, 
   "tls": true, 
   "host": "clust.mx.nwc.xxx",
   "authorization_method": "username_and_password"	
}

Response

Key	Type	Notes
status	string
msg	string

Successful status 200 OK
Response body schema:

json

{
  "status":"OK",
  "msg":"Connection successfully tested."
}

Errors

Cause	Response code	Message
"username" is empty string	400 Bad Request	"username": ["This field may not be blank."]
"username" is null	400 Bad Request	"username": ["This field may not be null."]
"username" has > 254 chars	400 Bad Request	"username": ["Ensure this field has no more than 254 characters."]
"password" is empty string	400 Bad Request	"password": ["This field may not be blank."]
"password" is null	400 Bad Request	"password": ["This field may not be null."]
"password" has > 128 chars	400 Bad Request	"password": ["Ensure this field has no more than 128 characters."]
"port" is required	400 Bad Request	"port": ["This field is required."]
"port" is invalid	400 Bad Request	"port": ["A valid integer is required."]
"port" < 0	400 Bad Request	"port": ["Ensure this value is greater than or equal to 0."]
"port" > 65535	400 Bad Request	"port": ["Ensure this value is less than or equal to 65535."]
"tls" invalid	400 Bad Request	"tls": ["Must be a valid boolean."]
"host" is required	400 Bad Request	"host": ["This field is required."]
"host" has > 63 chars	400 Bad Request	"host": ["Ensure this field has no more than 63 characters."]
Failure during Ms Graph testing	400 Bad Request	"detail": "Error. Please check username, authentication object and MS Graph settings"
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Integration configuration with "uuid" does not exist	404 Not Found	"detail": "Not found."

Integrations ​

Permissions ​

References ​

POST /api/integrations/ ​

Permissions ​

Request ​

Validations ​

Response ​

Errors ​

iManage ​

Request ​

Validations ​

Response ​

Errors ​

GET /api/integrations/ ​

Permissions ​

Request ​

Response ​

Response results array ​

Sorting ​

Filtering ​

Errors ​

GET /api/integrations/uuid/ ​

Permissions ​

Request ​

Response ​

Errors ​

iManage ​

Response ​

PATCH /api/integrations/uuid/ ​

Permissions ​

Request ​

Response ​

Errors ​

iManage ​

Request ​

Validations ​

Response ​

Errors ​

DELETE /api/integrations/uuid/ ​

Permissions ​

Request ​

Response ​

Errors ​

OPTIONS /api/integrations/ ​

Permissions ​

Request ​

Response ​

POST /api/integrations/test/ ​

Permissions ​

Request ​

Response ​

Errors ​

iManage ​

Request ​

Response ​

Errors ​

OPTIONS /api/administration/smtp-settings/ ​

Permissions ​

Request ​

Response ​

GET /api/administration/smtp-settings/ ​

Permissions ​

Request ​

Response ​

Errors ​

PATCH /api/administration/smtp-settings/ ​

Permissions ​

Request ​

Response ​

Errors ​

POST /api/administration/smtp-settings/test/ ​

Permissions ​

Request ​

Response ​

Errors ​

Integrations

Permissions

References

POST /api/integrations/

Permissions

Request

Validations

Response

Errors

iManage

Request

Validations

Response

Errors

GET /api/integrations/

Permissions

Request

Response

Response `results` array

Sorting

Filtering

Errors

GET /api/integrations/`uuid`/

Permissions

Request

Response

Errors

iManage

Response

PATCH /api/integrations/`uuid`/

Permissions

Request

Response

Errors

iManage

Request

Validations

Response

Errors

DELETE /api/integrations/`uuid`/

Permissions

Request

Response

Errors

OPTIONS /api/integrations/

Permissions

Request

Response

POST /api/integrations/test/

Permissions

Request

Response

Errors

iManage

Request

Response

Errors

OPTIONS /api/administration/smtp-settings/

Permissions

Request

Response

GET /api/administration/smtp-settings/

Permissions

Request

Response

Errors

PATCH /api/administration/smtp-settings/

Permissions

Request

Response

Errors

POST /api/administration/smtp-settings/test/

Permissions

Request

Response

Errors