Skip to main content
Skip table of contents

API Functions

If Allow unauthenticated requests option is disabled in the API key settings all functions except for login require a user token to be provided in the form of HTTP header: Authorization: Bearer <user_token>.

Get server version

  • Path: /version
  • Method: GET
  • Parameters: none
  • Returns: ServerVersionInfo
  • Errors: 403

Get account information

  • Path: /account
  • Method: GET, HEAD
  • Parameters: domainname: string optional domain name. If not specified the request address is used
  • Returns: AccountInfo for GET request, empty 200 status for HEAD request
  • Errors: 404
  • Notes: For HEAD request the X-API-Key header is not required

Create account

  • Path: /account
  • Method: PUT
  • Parameters:
    • parentdomain: string Domain name of parent account
    • accountname: string Name of the account
    • accounttype: int Type of the account: 1 = vendor, 2 = customer, 3 = container
    • domainname: string Account domain name. This parameter can be specified more than once
    • applicationname: string Account application name
    • [optional] trustallclients: bool Automatically trust the account value
    • [optional] locationid: int Id of existing location to be assigned to created account
  • Returns: ErrorCodeInfoId

cURL example:

CODE 
#!/bin/sh
`curl -X PUT -i -v -H "X-Api-Key:" -d "parentdomain=" -d "accountname=" -d "accounttype=" -d "domainname=" -d "domainname=" -d "applicationname=" -d "trustallclients=" -d "locationid=" -k "https://:7300/api/v1/account"`

Replace all with real values.

Get containers

  • Path: /account/containers
  • Method: GET
  • Parameters: None
  • Returns: list of ContainerInfo
  • Errors: 403

cURL example:

CODE 
curl -X GET -H "X-Api-Key: full_access_api_key" -k "https://server_name:7300/api/v1/account/containers"

Update container

  • Path: /account/container/*id*
  • Method: PUT
  • Parameters:
    • domainname: string Container domain name. This parameter can be specified more than once
    • containername: string Name of the container
    • [optional] applicationname: string Container application name
    • [optional] locationid: int Id of existing location to be assigned to container
  • Returns: ErrorCodeInfoId
  • Errors: 403, 404

cURL example:

CODE 
curl -X PUT -H "X-Api-Key: full_access_api_key" -k "https://server_name:7300/api/v1/account/container/CONTAINER_ID" -d domainname= -d domainname= -d containername= -d applicationname= -d locationid=

Replace all CONTAINER_ID with real value.

Delete container

  • Path: /account/container/*id*
  • Method: DELETE
  • Parameters:
    • [optional query parameter] withsubnodes: boolean true/false, whether to delete non-empty container
  • Returns: ErrorCodeInfoId
  • Errors: 403, 404

cURL example:

CODE 
curl -X DELETE -H "X-Api-Key: full_access_api_key" -k "https://server_name:7300/api/v1/account/container/CONTAINER_ID?withsubnodes=true"

Replace all CONTAINER_ID with real value.

User authentication

  • Path: /login
  • Method: POST
  • Parameters:
    • authtype: integer 0=password, 1=cardid, 2=shortid, 3=nameonly, 4=email
    • userid: string the id to authenticate
    • password: string an optional secret (required for authtype=0, optional for authtype=1, ignored for other types)
  • Returns: UserInfo
  • Errors: 401, 403

cURL example:

CODE 
#!/bin/sh
curl -X POST -H "X-Api-Key: key" -d "authtype=0" -d "userid=username" -d "password=password" "https://serveraddress:7300/api/v1/login"
If the “Allow untrusted endpoints” option is disabled in the API key settings this function requires a device token to be present in the form of HTTP header: Authorization: Bearer <device_token>

Get list of documents for user

  • Path: /documents
  • Method: GET
  • Parameters:
    • [optional] providerid: int The ID of the authentication provider for the given user. If not provided or zero server will attempt to guess it.
    • username: string name of the user
    • [optional] status: list[int] Status list for the documents. If not provided 0 => READY will be used. 0 => READY,1 => PRINTED, 2 => DELETED, 3 => EXPIRED, 4 => FAILED, 5 => RECEIVED, 6 => AWAITING_CONVERSION, 7 => CONVERTING, 8 => CONVERSION_FAILED, 9 => STORED
    • [optional] maxRecords: int The number of records to be retrieved. If not provided 50 is the default value. Max value 500
  • Returns: list of DocumentInfo
  • Errors: 403

Get documents’ history

Request should be equipped with API key that has full API access option ON.
If “Allow unauthenticated requests” option is disabled in the API key settings this function requires a device token to be present in the form of HTTP header:
Authorization: Bearer <user_token>. User, for which token was issued, should have ViewReports permission.

This endpoint is designed for getting raw document data for building custom dashboards. Since the output can potentially be very large, endpoint is equipped with paging functionality.

  • Path: /documents/history
  • Method: GET
  • Parameters:
    • [optional] maxrecords: int Maximum number of records on the single response page. Default value is 200, maximum is 2000.
    • [optional] pagetoken: string If number or records for your query exceeds maxrecords value, endpoint responds with exactly maxrecords documents and non-empty nextPageToken field. Use value of nextPageToken as a pagetoken parameter to get next page.
    • [optional] datestart: datetime ISO-8601 instant formatted start point for documents’ creation dates range. Example: 2021-09-21T16:38:10.972Z
    • [optional] dateend: datetime ISO-8601 instant formatted end point for documents’ creation dates range. Maximum allowed timeframe is 1 week. datestart should be less than dateend and the latter should be in future. The default value is “last 24 hours”.
    • [optional] domainname: string If you want to narrow the request scope to one of your accounts, you can provide its domain name. Queried account should be a sub-account related to the account you are querying. When this parameter is not provided, query is made against the account that has domain, taken from URL and all its subdomains.
    • [optional] username: string Exact login name of the user for which you want data to be delivered. When not specified, no filtering takes place.
    • [optional] portname: string Exact name of the port, where document was printed. When not specified, no filtering takes place.
    • [optional] status: list[int] Status list for the documents. When not specified, no filtering takes place. 0 => READY,1 => PRINTED, 2 => DELETED, 3 => EXPIRED, 4 => FAILED, 5 => RECEIVED, 6 => AWAITING_CONVERSION, 7 => CONVERTING, 8 => CONVERSION_FAILED, 9 => STORED.

Returns:

  • documents: array of DocumentInfo
  • recordsOnPage: Integer
  • nextPageToken: String
  • dateStart: String
  • dateEnd: String
  • domainName: String
  • userName: String
  • portName: String

DocumentInfo:

  • providerId: Int
  • uuid: String
  • documentName: String
  • documentType: Int
  • userName: String
  • totalPages: Int
  • colorPages: Int
  • duplex: Int
  • copies: Int
  • grayscale: Boolean
  • paperSize: String
  • dateTime: Long
  • storageOnline: Boolean
  • secure: Boolean
  • tags: list of TagInfo
  • collate: Boolean

  • status: I nt Type of Status: 0 => READY,1 => PRINTED, 2 => DELETED, 3 => EXPIRED, 4 => FAILED, 5 => RECEIVED, 6 => AWAITING_CONVERSION, 7 => CONVERTING, 8 => CONVERSION_FAILED, 9 => STORED

  • outputPortId: I nt
  • outputPortName: String

TagInfo

  • tagType: int Type of Tag: 0 = Department, 1 = Group
  • name: String Tag name

Usage example:
Example request

CODE 
curl --request GET 'https://yourhost:7300/api/v1/documents/history?datestart=2021-09-07T16:38:10.972Z&amp;dateend=2021-09-10T16:38:10.972Z&amp;domainname=testaccount1&amp;username=admin&amp;maxrecords=2' \
--header 'X-Api-Key: full-api-access-key' \

Example response

CODE 
{
    "documents": [
        {
            "providerId": 65,
            "uuid": "1b83f9ca-a05b-44cf-8c0b-ae7b4c934f92",
            "documentName": "Importand document 12345",
            "documentType": 0,
            "userName": "admin",
            "totalPages": 0,
            "colorPages": 0,
            "duplex": 0,
            "copies": 1,
            "grayscale": false,
            "paperSize": "",
            "dateTime": 1631205678743,
            "storageOnline": false,
            "tags": [
               {
                 "tagType": 0,
                 "name": "dev dep"
               },
               {
                 "tagType": 1,
                 "name": "dev"
               },
               {
                 "tagType": 1,
                 "name": "devsupport"
               }
             ]
        },
...
    ],
    "recordsOnPage": 2,
    "nextPageToken": "8a63ee56-3d9e-404f-a131-86b3bf9025b8",
    "dateStart": "2021-09-07T16:38:10.972Z",
    "dateEnd": "2021-09-10T16:38:10.972Z",
    "domainName": "testaccount1",
    "userName": "admin",
    "portName": ""
}

Presence of the nextPageToken means that there’s more data than you received on this page and you have to query next portion like the following:

CODE 
curl --location --request GET 'https://yourhost:7300/api/v1/documents/history?pagetoken=8a63ee56-3d9e-404f-a131-86b3bf9025b8' \
--header 'X-Api-Key: full-api-access-key' \

Repeat paging until returned nextPageToken becomes blank.

Record print/copy/scan jobs

The request can be authenticated either by using a device token or a user token.

  • If you wish to use a user token, the user for the job record is taken from the user token.
  • If you wish to use a device token, the user for the job record is taken from the required parameters "username" and "providerid".

In both cases, the request requires an API key configured with an authenticated request or a trusted endpoint.

  • Path: /documents/history
  • Method: POST
  • Parameters:
    • [required] jobtype: String Document job type: PRINT, COPY, SCAN, FAX.
    • [optional] totalpages: String Total pages of the document.
    • [optional] colorpages: String Color pages of the document.
    • [optional] papersize: String Size of document paper.
    • [optional] duplex: Boolean Types of duplex printing: If true use LONG otherwise SHORT.
    • [optional] title: String Title of the document.
    • [optional] serialnumber: String Serial number to find output port.
    • [optional] address: String Address to find output port.

    • [optional] username: String User name, if you use a device token.

    • [optional] providerid: String Authentication provider identifier, if you use a device token.

  • Returns: 200 Success
  • Errors: 400, 401, 403
  • Example request:
CODE 
curl -i -X POST -H "X-Api-Key:" -H "Authorization:" -d "jobtype=PRINT" "https://:7300/api/v1/documents/history"

Upload document

  • Path: /documents
  • Method: PUT
  • Parameters (multipart/form-data request):
    • [optional] providerid: int The ID of the authentication provider for the given user. If not provided or zero server will attempt to guess it.
    • data: form-data A multipart form parameter with Content-Disposition: form-data; name=“data”; filename=“xxx” header and
      content type application/octet-stream
    • username: string Name of the user
    • portname: string Name of the input port (queue)
    • title: string Document title
    • [optional] copies: string Number of copies
    • [optional] grayscale: string Should print grayscale true/false
    • [optional] duplex: string Duplex flag: 0=simplex, 1=long edge, 2=short edge
    • [optional] outputpagesize: string Output page size ("Original", "A3", "A4", "A5", "A6", "Letter", "Legal", "Ledger", "Tabloid" or custom "<Width>x<Height>" width and height in points - for example for A4 "595x842")

    • [optional] pageorientation: string Page orientation: 0 = portrait, 1 = landscape

      Some output page sizes do not support page orientation – like Ledger or Tabloid.

    • [optional] scale: string Scale in percent (1-100)
  • Returns: DocumentInfo
  • Errors: 403

cURL example:

CODE 
curl -X PUT -i -v -H "X-Api-Key: "  -F "username=" -F "portname=" -F "title=" -F "data=@;filename=" -k https://:7300/api/v1/documents

Replace all with real values.
The “@” symbol in -F "data=" is mandatory.

If the extension of the ‘filename’ is different than pdf, please make sure that you include that extension to the ‘title’ parameter.
For example, if the filename=file.docx, the title should be test.docx.

Parameters outputpagesize, pageorientation, and scale are supported only using the push print (when a job is sent directly to the printer).

With pull print (when a job is downloaded on MFD and printed), these parameters are ignored.


Uri upload is no longer supported for documents end point!

Delete document

  • Path: /documents/
  • Method: DELETE
  • Parameters:
    • uuid: pathparam Document UUID taken from request path
  • Returns: ErrorCodeInfo
  • Errors: 403

Send document to output port

  • Path: /documents/uuid/<address or SN>
  • Method: POST
  • Parameters:
    • uuid: pathparam Document UUID
    • address: pathparam Output port address
    • SN:   pathparam Output port serial number
    • copies: int Number of copies requested
    • grayscale: bool Whether to output in grayscale (true/false)
    • retain: bool Whether to keep the document after printing (true/false), default is false
    • duplex: int Duplex flag: 0=simplex, 1=long edge, 2=short edge
  • Rerurns: ErrorCodeInfo
  • Errors: 403

Get list of output ports for user

  • Path: /outputports
  • Method: GET
  • Parameters:
    • [optional] providerid: int The ID of the authentication provider for the given user. If not provided or zero server will attempt to guess it.
    • [optional] username: string name of the user for which the ports will be retrieved
  • Returns: list
  • Errors: 403

Create output port

  • Path: /outputports
  • Method: PUT
  • Parameters:
    • domainname: string Domain name of the parent account
    • portname: string Name of the port
    • address: string Port address
    • porttype: int Port type: 0 = dummy, 1 = printer
    • [optional] serviceid: int Id of the service (document output or terminal service) which this port will use. This parameter can be specified multiple times
    • [optional] vendor: string Short name of the printer vendor (unknown, fujifilm, ricoh, km, sharp, hp, lexmark, xerox, kyocera, toshiba, canon, brother, epson, eop)
    • [optional] embedded: bool Whether this printer has embedded client (true/false)
    • [optional] printprotocol: int Printing protocol: 0 = tcp, 1 = ipp, 2 = spooler (CUPS)
    • [optional] outputtype: int Output type: 0 = raw, 1 = PDF, 3 = PCL6, 4 = Postscript level 3, 5 = Postscript level 2. The value of 2 is deprecated and should not be used.
    • [optional] reversefinisher: bool Whether this printer has finisher with reversed path (true/false)
    • [optional] printerippurl: string Printer IPP URL
    • [optional] modelfamily: int printer model family: if PrinterVendor is RICOH => 0 = “Ricoh SDK/J” ;1 -> “Ricoh SOP” | if PrinterVendor is XEROX => 0 = “WorkCentre”; 1 = “AltaLink”; 2 = “VersaLink”
    • [optional] monochromeprinter: bool Monochrome printer (true/false)
    • [optional] ipreaderaddress: string IP Reader address
    • [optional] embeddedconfiguration: int Id of Embedded configuration
    • [optional] deviceserial: string IP Reader address
    • [optional] matchinginputport: bool If true a matching input port is automatically created (true/false)
    • [optional] description: string Port description
  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PUT -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports" -d domainname= -d portname= -d address= -d porttype= -d ipreaderaddress= -d deviceserial= -d reversefinisher= -d printerippurl= -d modelfamily= -d monochromeprinter= -d embeddedconfiguration= -d description=

Replace all with real values.

Update output port

  • Path: /outputports
  • Method: PUT
  • Parameters:
    • id: int Existing output port id
    • same parameters as for “Create output port”
  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PUT -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports" -d domainname= -d portname= -d address= -d porttype= -d ipreaderaddress= -d deviceserial= -d reversefinisher= -d printerippurl= -d modelfamily= -d monochromeprinter= -d embeddedconfiguration= -d description= -d id=

Replace all with real values.

Create input port

  • Path: /inputports
  • Method: PUT
  • Parameters:
    • domainname: string Domain name of the parent account
    • portname: string Name of the port
    • porttype: int Port type: 0 = Pull queue, 1 = Push queue
    • [optional] outputportid: int Id of the mapped output port for push queue types
    • [optional] portFlags: long flags of the input port. Each bit from the long value represents a flag. Flags: AvailableByDefault: …000001 (long value 1) – enabled and …000000 (long value 0) – disabled.
    • [optional] locationid: id Id of existing location to be assigned to created input port
  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PUT -H "X-Api-Key: full_access_api_key" -k "https://server_name:7300/api/v1/inputports" -d domainname= -d portname= -d porttype= -d outputportid= -d locationid=

Replace all with real values.

Update input port

  • Path: /inputports
  • Method: PUT
  • Parameters:
    • id: int Existing input port id
    • same parameters as for “Create input port”
  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PUT -H "X-Api-Key: full_access_api_key" -k "https://server_name:7300/api/v1/inputports" -d domainname= -d portname= -d porttype= -d outputportid= -d locationid= -d id=

Replace all with real values.

Get list of input ports for user

  • Path: /inputports
  • Method: GET
  • Parameters:
    • [optional] providerid: int The ID of the authentication provider for the given user. If not provided or zero server will attempt to guess it.
    • [optional] username: string name of the user for which the ports will be retrieved
    • [optional] locationids: int location id. This parameter can be specified more than once.
  • Returns: list
  • Errors: 403

Delete input port

  • Path: /inputports/
  • Method: DELETE
  • Parameters:
    • inputportid: pathparam Id of the input port to delete
  • Returns: ErrorCodeInfo
  • Errors: 403

Delete output port

  • Path: /outputports/
  • Method: DELETE
  • Parameters:
    • outputportid: pathparam Id of the output port to delete
  • Returns: ErrorCodeInfo
  • Errors: 403

Create user

  • Path: /users
  • Method: PUT
  • Parameters:
    • username: string Name of the user
    • [optional] providerid: int Identifier of the authentication provider under which the user will be created. If the providerid is not specified, the user will be created under a local provider.
    • [optional] detailtype: int Type of the user detail to add: 0=full name, 1=email, 2=homefolder, 3=password, 4=cardid, 5=shortid, 6=pin, 7=alias, 11=department
    • [optional] detaildata: string Detail data. detailtype and detaildata can be repeated multiple times
  • Returns: ErrorCodeInfo
  • Errors: 403

curl example:

CODE 
curl -X PUT -i -H X-Api-Key: -d username=john.doe -d detailtype=3 -d detaildata=password1 -d detailtype=1 -d detaildata=john.doe@cool.com -k https://account-domain-name:7300/api/v1/users
 
curl -X PUT -i -H X-Api-Key: -d username=john.doe -d providerid=129 -d detailtype=3 -d detaildata=password1 -d detailtype=1 -d detaildata=john.doe@cool.com -k https://account-domain-name:7300/api/v1/users

Delete user

  • Path: /users/<username>
  • Method: DELETE
  • Parameters:
    • username: pathparam Name of the user to delete
    • [optional query parameter] providerid: int Identifier of the authentication provider of the user who will be deleted. Users with the same username but different authentication providers will not be deleted. If the providerid is not specified, the user with the given username will be deleted from the local provider.
  • Returns: ErrorCodeInfo
  • Errors: 403

curl example:

CODE 
curl -X DELETE -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users/john.doe
 
curl -X DELETE -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users/john.doe?providerid=129


Update user details

  • Path: /users/<username>
  • Method: POST
  • Parameters:
    • username: pathparam Name of the user to update
    • [optional] providerid: int Identifier of the authentication provider where the user will be searched for. If the providerid is not specified, the user will be searched for in a local provider.
    • detailtype: int Type of the user detail to update: 0=full name, 1=email, 2=homefolder, 3=password, 4=cardid, 5=shortid, 6=pin, 7=alias
    • [optional] detaildata: string Detail data. If not specified the given detail is deleted from user. Alias can be specified with “#PID” suffix where PID is a provider ID, for example: “user@domain.com#1234”
  • Returns: ErrorCodeInfo
  • Errors: 403

curl example:

CODE 
curl -X POST -i -H X-Api-Key: -d detailtype=3 -d detaildata=password1 -k https://account-domain-name:7300/api/v1/users/john.doe

curl -X POST -i -H X-Api-Key: -d providerid=129 -d detailtype=3 -d detaildata=password1 -k https://account-domain-name:7300/api/v1/users/john.doe


Import users from csv

  • Path: /users/import
  • Method: POST
  • Parameters:
    • data: file Csv file in format: username;firstname;lastname;mail;usergroup
    • group: string Name of the local group where the usres will be imported
    • mapping: string Fields mapping in csv file (ex: userName:0,firstName:1,lastName:2,email:3,group:4)
    • [optional] separator: string Field separator in file (The default value is ‘,’)
    • [optional] hasheader: boolean Check if first row is a header inside the file (The default value is false)
    • [optional] async: string Check if to wait for the synchronization to be finished (The default value is false)
  • Returns: ErrorCodeInfo
  • Errors: 400

curl example:

CODE 
curl.exe -X POST -i -H X-Api-Key: --form-string "separator=;" -F "mapping=userName:0,firstName:1,lastName:2,email:3,group:4" -F "hasheader=false"  -F "group=" -F"data=@" -k https://account-domain-name:7300/api/v1/users/import
All imported users will be added to the group available in the request (-F “group=group_name”)
Only users part of the group sent in the request (-F “group=group_name”) will be deactivated after the synchronization

Register card for user

  • Path: /users/<username>/cards
  • Method: POST
  • Parameters:
    • username: pathparam Name of the user to whom is the card registered
    • cardid: string ID of the registered card
  • Returns: ErrorCodeInfo
  • Errors: 400, 403

curl example:

CODE 
curl -X POST -H "X-Api-Key: " -H "Authorization: " -k "https://:7300/api/v1/users/<username>/cards" -d cardid=

Replace all with real values.

Get authentication provider

  • Path: /authproviders
  • Method: GET
  • Parameters:
    • accountid= The ID of SAFEQ Cloud account domain
    • [optional] none
  • Returns: AuthenticationProvidersInfo
  • Errors: 400
  • Can be called without X-Api-Key, in this case, it will only return providers without any client/web secrets.

bash script example:

CODE 
#!/bin/sh
ACCOUNT_INFO=`curl -X GET -H "X-Api-Key:" -k https://:7300/api/v1/account`
echo "$ACCOUNT_INFO"
ACCOUNT_INFO_SED=$(echo "$ACCOUNT_INFO" | sed -E 's/.*"id":\s*(\S+)(,|}|\s).*/\1/g')
echo "$ACCOUNT_INFO_SED"
ACCOUNT_ID=$(echo "$ACCOUNT_INFO_SED" | cut -f1 -d ',')
echo "$ACCOUNT_ID"
LDAP_AUTH=`curl -X GET -i -H "" -k https://:7300/api/v1/authproviders?accountid="$ACCOUNT_ID"`
echo "$LDAP_AUTH"

Replace all with real values.

Add authentication provider

  • Path: /authproviders
  • Method: PUT
  • Parameters:
    • -d parameters include:
    • [name] – Name of authentication provider
    • [providerType] – 0 (local)/1 (LDAP)/2 (Microsoft Entra ID)/3 (okta)
    • [typeConfiguration] – authentication provider configuration details, for ex, for local provider it is {}
    • [accountID] – The ID of SAFEQ Cloud account domain
    • [priority] – defaults value is 0
    • [active] – true (authentication provider is active) / false (authentication provider is inactive)
    • [domainNames] – list of authorization provider domains
    • [id] – defaults as 0
    • [optional] none
  • Returns: ResponseCodeInfo
  • Errors: 400

bash script example to add an LDAP authentiation provider:

CODE 
#!/bin/sh
ACCOUNT_INFO=`curl -X GET -H "X-Api-Key:" -k https://:7300/api/v1/account`
echo "$ACCOUNT_INFO"
ACCOUNT_INFO_SED=$(echo "$ACCOUNT_INFO" | sed -E 's/.*"id":\s*(\S+)(,|}|\s).*/\1/g')
echo "$ACCOUNT_INFO_SED"
ACCOUNT_ID=$(echo "$ACCOUNT_INFO_SED" | cut -f1 -d ',')
echo "$ACCOUNT_ID"
LDAP_AUTH=`curl -X PUT -i -H "X-Api-Key:" -k https://:7300/api/v1/authproviders -d '{"name":"","providerType":1,"typeConfiguration":"{\"baseDN\":\"\",\"groupBaseDN\":\"\",\"address\":\"\",\"port\":389,\"ssl\":true,\"userName\":\"\",\"password\":\"\",\"active\":true,\"bindType\":0,\"searchMode\":0,\"userNameAttr\":\"\",\"fullNameAttr\":\"\",\"emailAttr\":\"\",\"cardId1Attr\":\"\",\"cardId2Attr\":\"\",\"shortIdAttr\":\"\",\"aliasAttr\":\"\",\"homeFolderAttr\":\"\",\"userAttrClass\":\"\",\"groupAttrClass\":\"\",\"nonEmptyAttrs\":[\"\",\"\",\"\",\"\",\"\",\"\",\"\",\"\"]}","accountId":'"$ACCOUNT_ID"',"priority":0,"active":true,"domainNames":["acme.com"],"id":0}'`
echo "$LDAP_AUTH"

Replace all with real values.

Delete authentication provider

  • Path: /authproviders/
  • Method: DELETE
  • Parameters: none
    • [optional] none
  • Returns: ResponseCodeInfo
  • Errors: 400

bash script example:

CODE 
#!/bin/sh
LDAP_AUTH=`curl -X DELETE -i -v -H "" -k https://:7300/api/v1/authproviders/`
echo "$LDAP_AUTH"

Replace all with real values.

Get access control details

  • Path: /accesscontrols
  • Method: GET
  • Parameters:
    • accountdomain= DNS name of account domain
    • [optional] permissionsdomain= DNS name of account’s parent domain. By specifying this parameter, you will get access controls for account domain, but defined at parent domain level.
  • Returns: AccessControlsInfo
  • Errors: 400

bash script example:

CODE 
#!/bin/sh
ACCESS_INFO=`curl -X GET -i -H "X-Api-Key:" -k https://:7300/api/v1/accesscontrols?accountdomain=`
echo "$ACCESS_INFO"

Replace all with real values.

Add access control

  • Path: /accesscontrols
  • Method: PUT
  • Parameters:
    • accountdomain= DNS name of account domain
    • --data parameters include:
    • [authProviderId] – ID of authentication provider for which access control is being added.
    • [roleName] – choose one based on scope – Administrators/Users/Reporting/Support
    • [userName] – use this parameter if assigning access control to user directly (see note below)
    • [groupName] – use this parameter if assigning access control to group directly (see note below)
    • [groupDn] – DN configuration of group/user
    • [optional] none
  • Returns: ResponseCodeInfo
  • Errors: 400

Note – Depending on whether you are assigning access control to a user or a group use “userName” or “groupName” parameter, but not both at the same time

bash script example to add access control for an LDAP group as Administrators in SAFEQ Cloud:

CODE 
#!/bin/sh
ACCESS_INFO=`curl -X PUT -i -H "" -k https://:7300/api/v1/accesscontrols?accountdomain= --data '{"authProviderId":,"roleName":"Administrators","groupName":"","groupDn":""}'`
echo "$ACCESS_INFO"

Replace all with real values.

Delete access control by id

  • Path: /accesscontrols/*id*
  • Method: DELETE
  • Parameters:
    • accountdomain= DNS name of account domain
    • [optional] none
  • Returns: ResponseCodeInfo
  • Errors: 400

bash script example:

CODE 
#!/bin/sh
ACCESS_INFO=`curl -X DELETE -i -H "" -k https://:7300/api/v1/accesscontrols/ACCESS_CONTROL_ID?accountdomain=`
echo "$ACCESS_INFO"

Replace all with real values.

When deleting an ACL record, perform a GET operation to check the current ACL ID before executing a DELETE operation. Do not execute two DELETE operations as the ID can change after the first one.


Get list of locations

  • Path: /locations
  • Method: GET
  • Parameters:
    • locationtype: int location type. This parameter can be specified more than once. Recognized types: 1 = gateway IPv4 address, 2 = IPv4 subnet, 3 = IPv4 range, 4 = WiFi SSID.
    • locationdata: string location search data. This parameter can be specified more than once and must correspond to the location type. Subnet is specified in the format “192.168.1.100/24”, IP range is specified in the format “192.168.1.100-192.168.1.200”.
  • Returns: list
  • Errors: 400
CODE 
#!/bin/sh
ACCESS_INFO=`curl -X GET -i -H "X-Api-Key:" -k "https://:7300/api/v1/locations?locationtype=1&amp;locationdata=192.168.1.100"`
echo "$ACCESS_INFO"

Replace all with real values.

Get location by id

  • Path: /locations
  • Method: GET
  • Parameters:
    • locationId= The location ID
  • Returns: LocationInfo
  • Errors: 404
CODE 
#!/bin/sh
ACCESS_INFO=`curl -X GET -i -H "X-Api-Key:" -k "https://:7300/api/v1/locations/"`
echo "$ACCESS_INFO"

Replace all with real values.

Create location

  • Path: /locations
  • Method: POST
  • Parameters: LocationInfo as JSON payload, except id property – skip it
  • Returns: ErrorCodeInfoId , id property will contain newly generated location identifier
  • Errors: 400, 403
CODE 
curl -X POST -H "X-Api-Key: full-api-access-key" -k "https://serveraddress:7300/api/v1/locations" --data-binary @- << EOF
{
        "name": "Location name",
        "identifiers": [
                {
                        "locationType": 1,
                        "stringData": [
                                "192.168.1.100"
                        ]
                }
        ]
}
EOF

Update existing location by id

  • Path: /locations/*id*
  • Method: PUT
  • Parameters: LocationInfo as JSON payload
  • Returns: LocationInfo
  • Errors: 400, 403, 404
CODE 
curl -X PUT -H "X-Api-Key: full-api-access-key" -k "https://serveraddress:7300/api/v1/locations/LOCATION_ID" --data-binary @- << EOF
{
        "name": "Location name",
        "identifiers": [
                {
                        "locationType": 1,
                        "stringData": [
                                "192.168.1.100"
                        ]
                }
        ]
}
EOF

Replace LOCATION_ID with real value.

Delete location by id

  • Path: /locations/*id*
  • Method: DELETE
  • Parameters: None
  • Returns: ErrorCodeInfoId
  • Errors: 403, 404
CODE 
curl -X DELETE -H "X-Api-Key: full-api-access-key" -k "https://serveraddress:7300/api/v1/locations/LOCATION_ID"

Replace LOCATION_ID with real value.

Release all jobs using the card reader

  • Path: /card
  • Method: GET, POST
  • Parameters:
    • cd: string required user card reader id
    • Mac: string required printer ip card reader address
  • Returns: 200 Success
  • Errors: 400
  • Notes: For POST method the parameters must be sent as query parameters and not body parameters.

cURL example:

CODE 
curl -X GET -i -v -H "X-Api-Key: " -k "https://:7300/api/v1/card/?cd=&amp;amp;Mac="

Get list of local groups

  • Path: /groups
  • Method: GET
  • Parameters:
  • Returns: list

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups"

Create local user group

  • Path: /groups
  • Method: PUT
  • Parameters:
    • groupname: string required local group name
    • groupdn optional group ID. If omitted a unique group ID will be generated
  • Returns: ErrorCodeInfo which contains new group id
  • Errors: 400

cURL example:

CODE 
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups" -d  groupname= -d groupdn=

Delete local user group

  • Path: /groups/
  • Method: DELETE
  • Parameters:
    • GROUPID: pathparam path parameter which indicates either group primary key (integer) or group ID (string)
  • Returns: ErrorCodeInfo

cURL example:

CODE 
curl -X DELETE -i -v -H "X-Api-Key: " -k "https://:7300/api/v1/groups/"

Get info about group

  • Path: /groups/GROUPID

  • Method: GET

  • Parameters:

    • GROUPID: pathparam path parameter which indicates either group primary key (integer) or group ID (string)

  • Returns: GroupInfo

  • Errors: 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups/GROUPID"

Get members of a group

  • Path: /groups/GROUPID/members

  • Method: GET
  • Parameters:

    • GROUPID: pathparam path parameter which indicates either group primary key (integer) or group ID (string)

  • Returns: List<UserInfo>

  • Errors: 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups/GROUPID/members"


Get list of groups for a given local user

  • Path: /users/USERNAME/groups
  • Method: GET
  • Parameters:
    • USERNAME: pathparam path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser: /users/testuser/groups
  • Returns: list
  • Errors: 400

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/users//groups"
CODE 
curl -X GET -i -H  'X-Api-Key:46405b18-8e1b-4db9-b930-bedd9ae839af' -k https://cloud.test.local:7300/api/v1/users/mytestuser/groups

Add local user to a list of provided groups

  • Path: /users/USERNAME/groups
  • Method: PUT
  • Parameters:
    • USERNAME: pathparam path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser: /users/testuser/groups
    • groupid: string one or more group ids to which this user must be added. Each id can be either a group primary key or textual group ID.
  • Returns: ErrorCodeInfo
  • Errors: 400

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/users//groups" -d groupid=

Set local user membership to a list of provided groups

  • Path: /users/USERNAME/groups
  • Method: POST
  • Parameters:
    • USERNAME: pathparam path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser: /users/testuser/groups
    • groupid: string zero or more group ids which will be set as user’s groups. The current groups will be removed from the user. Each id can be either a group primary key or textual group ID. If this parameter is not provided all groups will be cleared.
  • Returns: ErrorCodeInfo
  • Errors: 400

Delete groups from user’s membership

  • Path: /users/USERNAME/groups
  • Method: DELETE
  • Parameters:
    • USERNAME: pathparam path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser: /users/testuser/groups
    • groupid: string one or more group ids to delete from user’s membership. Each id can be either a group primary key or textual group ID.
  • Returns: ErrorCodeInfo
  • Errors: 400

cURL example:

CODE 
curl -X DELETE -i -H "X-Api-Key: " -k "https://:7300/api/v1/users//groups" -d groupid=

Create terminal configuration

  • Path: /terminalconfig
  • Method: POST
  • Parameters:
    • domain: string required account domain where to add the configuration
    • name: string required configuration name
    • vendor: string required printer vendor (ex: km, hp, xerox ….)
    • adminuser: string optional admin username. If omitted empty is the default
    • adminpassword: string optional admin password. If omitted empty is the default
    • applicationtype: int optional application type (ex: 0:Other, 1:Open_API, 2: IWS, 3: Workpath). If omitted OTHER is the default
    • devices: int optional list of mapped output ports ids. Can be repeated multiple times
  • Returns: ErrorCodeInfo which contains new terminal config id
  • Errors: 400

cURL example:

CODE 
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/terminalconfig" -d  domain= -d name= -d vendor= -d adminuser= -d adminpassword= -d applicationtype= -d devices=

Get terminal configuration

  • Path: /terminalconfig
  • Method: GET
  • Parameters:
    • serialnumber: string required serial number (device serial) of the printer
  • Returns: TerminalConfig
  • Errors: 400, 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " "https://:7300/api/v1/terminalconfig?serialnumber="
CODE 
curl -X GET -i -H "X-Api-Key: " -H "Authorization: " "https://:7300/api/v1/terminalconfig?serialnumber="

Refresh user token

  • Path: /token
  • Method: GET
  • Parameters:
    • refresh_token: string a refresh token acquired in the login call
  • Returns: TokenInfo
  • Errors: 400, 403
A given refresh token can only be used once. The next call to a refresh function should be done with a new refresh token.

cURL example:

CODE 
curl -i -H "X-Api-Key: xxx" -k "https://serveraddress:7300/api/v1/token?refresh_token=yyy"

Scan Connectors

Note

This feature is currently hidden by default and may not be available for your account.

Get scan connector

  • Path: /scan/connectors/<scanConnectorId>

  • Method: GET

  • Parameters:

    • scanConnectorId: int Id of the connector

  • Returns: ScanConnectorInfo

  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors/<scanConnectorId>"

Get all scan connectors

  • Path: /scan/connectors

  • Method: GET

  • Returns: list<ScanConnectorInfo>

  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors"

Update scan connector

  • Path: /scan/connectors/<scanConnectorId>

  • Method: PUT

  • Parameters:

    • scanConnectorId: int Id of the connector

    • scanConnector: ScanConnectorInfo – see Data structures

  • Returns: ScanConnectorInfo

  • Errors: 403, 404

cURL example:

CODE 
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors/<scanConnectorId>" --data "{\"name\":\"Connector\", \"connectorType\":\"EMAIL\"}"

Create scan connector

  • Path: /scan/connectors

  • Method: POST

  • Parameters:

  • Returns: ScanConnectorInfo

  • Errors: 403, 404

cURL example:

CODE 
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors" --data "{\"name\":\"Connector\", \"connectorType\":\"EMAIL\"}"

Delete scan connector

  • Path: /scan/connectors/<scanConnectorId>

  • Method: DELETE

  • Parameters:

    • scanConnectorId: int Id of the connector

  • Returns: 204

  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors/<scanConnectorId>"

Scan Workflows

Note

This feature is currently hidden by default and may not be available for your account.

Get scan workflow

  • Path: /scan/workflows/<scanWorkflowId>

  • Method: GET

  • Parameters:

    • scanWorkflowId: int Id of the workflow

  • Returns: ScanWorkflowTemplateInfo

  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows/<scanWorkflowId>"

Get all scan workflows

  • Path: /scan/workflows
  • Method: GET
  • Returns: list<ScanWorkflowTemplateInfo>
  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows"

Update scan workflow

  • Path: /scan/workflows/<scanWorkflowId>
  • Method: PUT
  • Parameters:
    • scanWorkflowId: int Id of the workflow
    • scanWorkflow: ScanWorkflowTemplateInfo – see Data structures
  • Returns: ScanWorkflowTemplateInfo
  • Errors: 403, 404

cURL example:

CODE 
curl -X PUT -i -H "X-Api-Key: " -k 
"https://:7300/api/v1/scan/workflows/<scanWorkflowId>" --data "{\"name\":\"Workflow\", \"connectorId\":<scanConnectorId>}"

Create scan workflows

  • Path: /scan/workflows
  • Method: POST
  • Parameters:
  • Returns: ScanWorkflowTemplateInfo
  • Errors: 403, 404

cURL example:

CODE 
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows" --data "{\"name\":\"Workflow\", \"connectorId\":<scanConnectorId>}"

Delete scan workflow

  • Path: /scan/workflows/<scanWorkflowId>
  • Method: DELETE
  • Parameters:
    • scanWorkflowId: int Id of the workflow
  • Returns: 204
  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows/<scanWorkflowId>"

Scan Workflow Access

This feature is currently hidden by default and may not be available for your account.

Get scan workflow access

  • Path: /scan/access/<accessId>
  • Method: GET
  • Parameters:
    • accessId: int Id of the workflow access
  • Returns: ScanWorkflowAccessInfo
  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access/<accessId>"

Get all scan workflow accesses

  • Path: /scan/access
  • Method: GET
  • Returns: list<ScanWorkflowAccessInfo>
  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access"

Update scan workflow access

  • Path: /scan/access/<accessId>
  • Method: PUT
  • Parameters:
    • accessId: int Id of the workflow access
    • accessInfo: ScanWorkflowAccessInfo – see Data structures
  • Returns: ScanWorkflowAccessInfo
  • Errors: 403, 404

cURL example:

CODE 
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access/<accessId>" --data "{\"workflowId\":\"100\", \"identityId\":2, \"identityType\":\"Group\"}"

Create scan workflow access

  • Path: /scan/access
  • Method: POST
  • Parameters:
  • Returns: ScanWorkflowTemplateInfo
  • Errors: 403, 404

cURL example:

CODE 
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access" --data "{\"workflowId\":\"1\", \"identityId\":2, \"identityType\":\"User\"}"

Delete scan workflow access

  • Path: /scan/access/<accessId>
  • Method: DELETE
  • Parameters:
    • accessId: int Id of the workflow access
  • Returns: 204
  • Errors: 403, 404

cURL example:

CODE 
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access/<accessId>"
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close