Skip to main content
Skip table of contents

API Functions

Common / Security

API key permissions

Almost all API functions require Advanced API permissions on API key to be checked and a precise list of rights to be selected. An API call that does not require this option has a note "Does not require Advanced API permissions."

Advanced API permissions allow to address the power of the API key for exact API functions. Whenever the Advanced API permissions option is selected, the permissions are checked within the API call, even if the API call does not require this access level.

Each API function has the "Permission info" note, where the list of required permissions is mentioned.

When the user token is used within the API call, the API key used for login has to match the API key used for the API call. The user token contains the user permissions that must match the "Permission info" note in each API call. For API calls whose descriptions do not contain a note "Does not require Advanced API permissions.", the "Advanced API permissions" of the used API key must correspond to the permissions listed in the "Permission info" note in each API call.

Security

We highly recommend you to use this option and select only the necessary permissions for each API key.

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

Version

Get server version

Permission info

Does not require Advanced API permissions.

Path: /version

  • Method: GET

  • Parameters: none

  • Returns: ServerVersionInfo

    ord  print/copy/scan jobs:

  • Errors: 403

Account

Get account information

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccount permission.

Does not require Advanced API permissions.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccount and CreateAccount permissions.

  • Path: /account

  • Method: PUT

  • Parameters:

    • parentdomain: string The domain name of the 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. The domain name can contain letters, numbers, hyphens, and periods. Any part of the domain name (separated by a period) should begin and end with a letter or number.

    • applicationname: string Account application name

    • [optional] trustallclients: bool Automatically trust the account value

    • [optional] locationid: int Id of the existing location to be assigned to the 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.

Update account

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewAccount and ModifyAccount permissions.

  • Path: /account

  • Method: PATCH

  • Parameters:

    • [optional] accountname: string Name of the account

    • [optional] domainname: string Account domain name. This parameter can be specified more than once
      A domain name can contain letters, numbers, hyphens, and periods. Any part of the domain name (separated by a period) should begin and end with a letter or number.

    • [optional] applicationname: string Account application name

    • [optional] trustallclients: string Automatically trust the account value

    • [optional] locationid: string Id of the existing location to be assigned to the created account

    • [optional] locale: string Account's language - expected values: "pt-BR" (Brazilian Portuguese), "zh" (Chinese), "cs" (Czech), "da" (Danish), "nl" (Dutch), "en" (English), "fr" (French), "de" (German), "id" (Indonesian), "it" (Italian), "ja" (Japanese), "ko" (Korean), "ms" (Malay), "no" (Norwegian), "pl" (Polish), "pt" (Portuguese), "sk" (Slovak), "es" (Spanish), "sv" (Swedish), "th" (Thai)

    • [optional] defaultpapersize: string Account's default paper size - expected values: "A3", "A4", "A5", "Letter"

    • [optional] theme: string Account's color theme - expected values: "blue", "orange", "purple", "red", "green", "breeze" 

  • Returns: ErrorCodeInfoId

cURL example:

CODE 
curl -X PATCH "https://server_name:7300/api/v1/account" -H "X-Api-Key: key" -d "accountname=" -d "domainname=" -d "applicationname=" -d "trustallclients=" -d "locationid=" -d "locale=" -d "defaultpapersize=" -d "theme="

Get containers

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccount permission.

  • Path: /account/containers

  • Method: GET

  • Parameters: None

  • Returns: list of ContainerInfo

  • Errors: 403

cURL example:

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

Update container

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccount and ModifyAccount permissions.

  • 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 the existing location to be assigned to the container

  • Returns: ErrorCodeInfoId

  • Errors: 403, 404

cURL example:

CODE 
curl -X PUT -H "X-Api-Key: advanced_api_permissions_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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccount and DeleteAccount permissions.

  • Path: /account/container/*id*

  • Method: DELETE

  • Parameters:

    • [optional query parameter] withsubnodes: boolean true/false, whether to delete the non-empty container

  • Returns: ErrorCodeInfoId

  • Errors: 403, 404

cURL example:

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

Replace all CONTAINER_ID with real value.

Login

User authentication

Permission info

Does not require Advanced API permissions.

Authorization with a device token or allowing untrusted endpoints is required .

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"

Documents

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 an HTTP header: Authorization: Bearer <device_token>

Get list of documents for user

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewJob permission.

Does not require Advanced API permissions.

Authorization with user token is required. Cannot call with an insecure API key.

  • Path: /documents

  • Method: GET

  • Parameters:

    • [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. For more details see Document Status Flowchart.

    • [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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewReport permission.

Restriction info

Only available for Customer account type. It is not possible to call this on Vendor or Container account types. In such case, the call returns a 400 error.

Restriction info

The timeout for this API endpoint is 5 minutes.

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

  • Path: /documents/history

  • Method: GET

  • Parameters:

    • [optional] maxrecords: int Maximum number of records on the single response page. The default value is 200, maximum is 2000.

    • [optional] pagetoken: string If the number or records for your query exceeds maxrecords value, the endpoint responds with exactly maxrecords documents and non-empty nextPageToken field. Use value of nextPageToken as a pagetoken parameter to get the 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 endpoint for documents’ creation dates range. The maximum allowed timeframe is 1 week. datestart should be less than dateend , and the latter should be in the 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, the query is made against the account that has domain, taken from URL and all its subdomains.

    • [optional] username: string The exact login name of the user for which you want data to be delivered. When not specified, no filtering takes place.

    • [optional] portname: string The exact name of the port where the 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. For more details see Document Status Flowchart.

    • [optional] jobtype: string Document job type (PRINT, COPY, SCAN, FAX)

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[TagInfo]

  • collate: Boolean

  • status: Int 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. For more details see Document Status Flowchart.

  • outputPortId: Int

  • outputPortName: String

  • jobType: String (PRINT, COPY, SCAN, FAX)

  • scanWorkflowId: Int

  • scanConnectorId: Int

TagInfo

  • tagType: Int Type of Tag: 0 = Department, 1 = Group

  • name: String Tag name

Errors: 400

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: advanced_api_permissions_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"
               }
             ],
			"collate": false,
			"status": 1,
			"outputPortId": 1,
			"outputPortName" "Test printer",
			"jobType": "PRINT"
        },
...
    ],
    "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: advanced_api_permissions_key' \

Repeat paging until returned nextPageToken becomes blank.

Record print/copy/scan jobs:

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

  1. If you want to use a user token, the user for the job record is taken from the user token.

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

In any case, the request requires 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.

    • [optional] datetime: String Date time in format YYYY-MM-DDTHH:mm:ss+HH:mm to set concrete time of the record.

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the AddJob permission.

Does not require Advanced API permissions.

  • 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, the 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 (Note: Some page output page sizes do not support page orientation - like Ledger or Tabloid.)

    • [optional] scale : string Scale in percent (1-100)

  • Returns: DocumentInfo

  • Errors: 400, 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.

Limitations for uploading MS Office files:

  • The maximum document size the user can upload is 200 MB.

  • Print preview of one Microsoft Excel file can contain at most 10 thousand pages.

  • The duration of conversion from MS Office files to PDF is limited to 5 minutes.

If the user exceeds any of these limitations, it will result in conversion failure.

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

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

Uri upload is no longer supported for documents endpoint!

Delete document

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewJob and DeleteJob permissions.

Does not require Advanced API permissions for a user who owns the document.

  • Path: /documents/

  • Method: DELETE

  • Parameters:

    • uuid: pathparam Document UUID taken from the request path

  • Returns: ErrorCodeInfo

  • Errors: 403

Send document to output port

Permission info

If you provide a user token, make sure the user for whom the token was issued has ReleaseJob permission.

Does not require Advanced API permissions for a user who owns the document.

An insecure API key is not allowed for this request.

  • 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

  • Returns: ErrorCodeInfo

  • Errors: 400, 403

Content

Content-type application/x-www-form-urlencoded has to be specified even when no additional parameters are specified.

Download document

Permission info

If you provide a user token, make sure the user, for whom the token was issued, has ViewJob permission.

Does not require Advanced API permissions for a user who owns the document.

Insecure API key is not allowed for this request.

  • Path: /documents/uuid.content

  • Method: GET

  • Parameters:

    • uuid: pathparam Document UUID

    • 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

  • Returns: 200 Success

  • Errors: 400, 403, 404, 503

Output Ports

Get list of output ports for user

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort permission.

  • Path: /outputports

  • Method: GET

  • Parameters:

    • [optional] providerid: int The ID of the authentication provider for the given user. If not provided or zero, the server will attempt to guess it.

    • [optional] username: string name of the user for which the ports will be retrieved

    • [optional] enrichPorts: boolean specify whether ports should include additional information, such as account, container and location id. Default: false

  • Returns: list

  • Errors: 403

Create output port - POST

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and CreateOutputPort permissions.

  • Path: /outputports

  • Method: POST

  • 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 a 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

    • [optional] softwareCopyCollation: bool Use software copy collation instead of internal printer copy collation (true/false)

    • [optional] sendusername: bool Jobs printed on this output port contain usernames instead of anonymous (true/false) (IPP only)

  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X POST -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 softwareCopyCollation= -d sendusername=

Replace all with real values.

Create output port - PUT

This endpoint is being deprecated and will not be updated in future releases, please use POST create output port endpoint above.

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and CreateOutputPort permissions.

  • 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 a 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

    • [optional] softwareCopyCollation: bool Use software copy collation instead of internal printer copy collation (true/false)

  • 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 - PATCH

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and ModifyOutputPort permissions.

  • Path: /outputports/<outputportid>

  • Method: PATCH

  • Parameters:

    • outputportid: pathparam Existing output port id

    • 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 a 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

    • [optional] softwareCopyCollation: bool Use software copy collation instead of internal printer copy collation (true/false)

    • [optional] sendusername: bool Jobs printed on this output port contain usernames instead of anonymous (true/false) (IPP only)

  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PATCH -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports/<outputportid>" -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 softwareCopyCollation= -d sendusername=

Replace all with real values.

Update output port - PUT

This endpoint is being deprecated and will not be updated in future releases, please use PATCH update output port endpoint above.

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and ModifyOutputPort permissions.

  • Path: /outputports

  • Method: PUT

  • Parameters:

    • id: int Existing output port id

    • same parameters as for “Create output port - PUT”

  • 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.

Move output port

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and ModifyOutputPort permissions.

  • Path: /outputports/<outputportid>/move

  • Method: PUT

  • Parameters:

    • outputportid: pathparam Existing output port id

    • domainname: string Domain name of the parent account

    • destinationdomainname: string Specifies the domain name of the target account or container where the output port will be moved in the tree

  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PUT -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports/<outputportid>/move" -d domainname= -d destinationdomainname

Replace all with real values.

The output port can only be moved within the same parent account and cannot be transferred outside of its current account hierarchy.

Delete output port

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and DeleteOutputPort permissions.

  • Path: /outputports/

  • Method: DELETE

  • Parameters:

    • outputportid: pathparam Id of the output port to delete

  • Returns: ErrorCodeInfo

  • Errors: 403

Input Ports

Create input port

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewInputPort and CreateInputPort permissions.

  • 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 the existing location to be assigned to the created input port

  • Returns: ErrorCodeInfoId

curl example:

CODE 
curl -X PUT -H "X-Api-Key: advanced_api_permissions_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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewInputPort and ModifyInputPort permissions.

  • 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: advanced_api_permissions_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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewInputPort permission.

Does not require Advanced API permissions.

  • Path: /inputports

  • Method: GET

  • Parameters:

    • [optional] providerid: int The ID of the authentication provider for the given user. If not provided or zero, the 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.

    • [optional] enrichPorts: boolean specify whether ports should include additional information, such as account, container and location id. Default: false

  • Returns: list

  • Errors: 403

Delete input port

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewInputPort and DeleteInputPort permissions.

  • Path: /inputports/

  • Method: DELETE

  • Parameters:

    • inputportid: pathparam Id of the input port to delete

  • Returns: ErrorCodeInfo

  • Errors: 403

Users

Get user information

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewUser permission.

  • Path:  /users

  • Method:  GET

  • Parameters:

    • username: string  Name of the user

    • providerid   : int  Identifier of the authentication provider to which the user belongs.

  • Returns:  UserInfo

  • Errors: 403, 404

Curl example:

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

Get all users of authentication provider

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewUser permission.

  • Path:  /users/all

  • Method:  GET

  • Parameters:

    • providerid : int  Identifier of the authentication provider to which the user belongs.

    • [optional] maxrecords: int Maximum number of records on the single response page. The default value is 50, maximum is 1000.

    • [optional] pagetoken: string If the number of records for your query exceeds maxrecords value, the endpoint responds with exactly maxrecords number of users and non-empty nextPageToken field. Use value of nextPageToken as a pagetoken parameter to get the next page.

  • Returns:  List<UserInfo>

  • Errors: 403

Curl example:

CODE 
curl -X GET -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users/all?providerid=3

curl -X GET -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users/all?providerid=3&pagetoken=50&maxrecords=100

Create user

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewUser and CreateUser permissions.

  • 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, 12=expiration, 14=externalid

    • [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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewUser and DeleteUser permissions.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewUser, ModifyUser, GenerateShortID, GenerateOTP, and CardManagement permissions.

GenerateShortID, GenerateOTP, or CardManagement permissions are required only when the Short ID, One time password, or Card number is updated. If you do not change any of these values, none of these permissions is required.

  • 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, 11=department, 12=expiration, 14=externalid

    • [optional] detaildata: string Detail data. If not specified, the given detail is deleted from the user. An alias can be specified with “#PID” suffix where PID is a provider ID, for example: “user@domain.com#1234”

    • Note that this API call can update only one user detail. If multiple details are provided, only the first will be updated.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has CreateUser and ModifyUser permissions.

  • 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 users 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 the first row is a header inside the file (The default value is false)

    • [optional] async: string Check if you wish to wait for the synchronization to be finished (The default value is false)

  • Returns: ErrorCodeInfo

  • Errors: 400

curl example:

CODE 
curl -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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser, ModifyUser, and CardManagement permissions.

Does not require Advanced API permissions.

  • Path: /users/<username>/cards

  • Method: POST

  • Parameters:

    • username: pathparam  Name of the user to whom the card is registered

    • cardid: string The ID of the registered card

  • Returns: ErrorCodeInfo

  • Errors: 400, 403

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

Get list of groups for a given local user

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser permission.

  • 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://CloudStream1.test.local:7300/api/v1/users/mytestuser/groups

Add local user to a list of provided groups

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser and ModifyUser permissions.

  • 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 a 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser and ModifyUser permissions.

  • 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 groups. The current groups will be removed from the user. Each ID can be either a group primary key or a textual group ID. If this parameter is not provided, all groups will be cleared.

  • Returns: ErrorCodeInfo

  • Errors: 400

Delete groups from user’s membership

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser and ModifyUser permissions.

  • 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 the user’s membership. Each ID can be either a group primary key or a 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=

Authentication provider

Get authentication provider

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAuthenticationProviders permission.

  • Path: /authproviders

  • Method: GET

  • Parameters:

    • accountid= The ID of CloudStream 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAuthenticationProviders and ModifyAuthenticationProviders permissions.

  • 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 example, for local provider, it is {}

    • [accountID] – The ID of CloudStream account domain

    • [priority] – default 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 authentication 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAuthenticationProviders and DeleteAuthenticationProviders permissions.

  • 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.

Access controls

Availability on secondary/gateway servers

All access controls endpoints work on primary servers only. If you call these endpoints on secondary/gateway server, you will receive status code 400 Bad Request.

Get access control details

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccessControls permission.

  • Path: /accesscontrols

  • Method: GET

  • Parameters:

    • accountdomain= DNS name of account domain

    • [optional] permissionsdomain= DNS name of the account’s parent domain. By specifying this parameter, you will get access controls for the account domain, but defined at the 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccessControls and CreateAccessControls permissions.

  • Path: /accesscontrols

  • Method: PUT

  • Parameters:

    • accountdomain= DNS name of account domain

    • --data parameters include:

    • [authProviderId] – ID of the 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 the user directly (see note below)

    • [groupName] – use this parameter if assigning access control to the 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 CloudStream:

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewAccessControls and DeleteAccessControls permissions.

  • 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.

Warning

Delete ACL can trigger resorting of ACL IDs. Before every DELETE operation call GET operation to check what is current ACL ID. Never call two DELETE operations because ID can change after the first DELETE. operation

Locations

Get list of locations

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewLocations permission.

Does not require Advanced API permissions.

  • 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. The 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewLocations permission.

Does not require Advanced API permissions.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewLocations and CreateLocations permissions.

  • Path: /locations

  • Method: POST

  • Parameters: LocationInfo as JSON payload, except id property – skip it

  • Returns: ErrorCodeInfoId , id property will contain a newly generated location identifier

  • Errors: 400, 403

CODE 
curl -X POST -H "X-Api-Key: advanced_api_permissions_key" -k "https://serveraddress:7300/api/v1/locations" --data-binary @- &lt;&lt; EOF
{
        "name": "Location name",
        "identifiers": [
                {
                        "locationType": 1,
                        "stringData": [
                                "192.168.1.100"
                        ]
                }
        ]
}
EOF

Update existing location by id

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewLocations and ModifyLocations permissions.

  • Path: /locations/*id*

  • Method: PUT

  • Parameters: LocationInfo as JSON payload

  • Returns: LocationInfo

  • Errors: 400, 403, 404

CODE 
curl -X PUT -H "X-Api-Key: advanced_api_permissions_key" -k "https://serveraddress:7300/api/v1/locations/LOCATION_ID" --data-binary @- &lt;&lt; EOF
{
        "name": "Location name",
        "identifiers": [
                {
                        "locationType": 1,
                        "stringData": [
                                "192.168.1.100"
                        ]
                }
        ]
}
EOF

Replace LOCATION_ID with real value.

Delete location by id

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewLocations and DeleteLocations permissions.

  • Path: /locations/*id*

  • Method: DELETE

  • Parameters: None

  • Returns: ErrorCodeInfoId

  • Errors: 403, 404

CODE 
curl -X DELETE -H "X-Api-Key: advanced_api_permissions_key" -k "https://serveraddress:7300/api/v1/locations/LOCATION_ID"

Replace LOCATION_ID with real value.

Card reader

Release all jobs using the card reader

Permission info

Does not require Advanced API permissions.

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, 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="

Groups

Get list of local groups

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser permission.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewUser and CreateUser permissions.

  • 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 a 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser and DeleteUser permissions.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser permission.

  • 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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewUser permissions.

  • 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"

Terminal config

Create terminal configuration

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewTerminalConfig and CreateTerminalConfig permissions.

  • 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 port IDs. Can be repeated multiple times

  • Returns: ErrorCodeInfo which contains the 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

Permission info

Does not require Advanced API permissions.

Authorization with a device token or allowing untrusted endpoints is required .

This feature is only available for the Ricoh Standard Embedded Terminal.

  • 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="

Token

Permission info

Does not require Advanced API permissions.

This function is deprecated and will be removed in future versions. Use the /oauth/v1/token endpoint to refresh both user and device tokens. See the Refresh device or user token chapter for more information.

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow permission.

  • Path: /scan/connectors/<scanConnectorId>

  • Method: GET

  • Parameters:

    • scanConnectorId: int Id of the connector

  • Returns: ScanConnectorInfo

  • Errors: 403, 404

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

Get all scan connectors

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow permission.

  • Path: /scan/connectors

  • Method: GET

  • Returns: list<ScanConnectorInfo>

  • Errors: 403, 404

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

Update scan connector

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and ModifyScanWorkflow permissions.

  • Path: /scan/connectors/<scanConnectorId>

  • Method: PUT

  • Parameters:

    • scanConnectorId: int Id of the connector

    • scanConnector: ScanConnectorInfo - see Data structures.

  • Returns: ScanConnectorInfo

  • Errors: 403, 404

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and CreateScanWorkflow permissions.

  • Path: /scan/connectors

  • Method: POST

  • Parameters:

  • Returns: ScanConnectorInfo

  • Errors: 403, 404

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

Delete scan connector

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and DeleteScanWorkflow permissions.

  • Path: /scan/connectors/<scanConnectorId>

  • Method: DELETE

  • Parameters:

    • scanConnectorId: int Id of the connector

  • Returns: 204

  • Errors: 403, 404

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow permission.

  • Path: /scan/workflows/<scanWorkflowId>

  • Method: GET

  • Parameters:

    • scanWorkflowId: int Id of the workflow

  • Returns: ScanWorkflowTemplateInfo

  • Errors: 403, 404

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

Get all scan workflows

Permission info

If you provide a user token, make sure the user for whom the token was issued has ViewScanWorkflow permission.

  • Path: /scan/workflows

  • Method: GET

  • Returns: list<ScanWorkflowTemplateInfo>

  • Errors: 403, 404

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

Update scan workflow

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and ModifyScanWorkflow permissions.

  • Path: /scan/workflows/<scanWorkflowId>

  • Method: PUT

  • Parameters:

    • scanWorkflowId: int Id of the workflow

    • scanWorkflow: ScanWorkflowTemplateInfo - see Data structures.

  • Returns: ScanWorkflowTemplateInfo

  • Errors: 403, 404

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and CreateScanWorkflow permissions.

  • Path: /scan/workflows

  • Method: POST

  • Parameters:

  • Returns: ScanWorkflowTemplateInfo

  • Errors: 403, 404

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

Delete scan workflow

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and DeleteScanWorkflow permissions.

  • Path: /scan/workflows/<scanWorkflowId>

  • Method: DELETE

  • Parameters:

    • scanWorkflowId: int Id of the workflow

  • Returns: 204

  • Errors: 403, 404

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

Scan Workflow Access

Note

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

Get scan workflow access

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule permission.

  • Path: /scan/access/<accessId>

  • Method: GET

  • Parameters:

    • accessId: int Id of the workflow access

  • Returns: ScanWorkflowAccessInfo

  • Errors: 403, 404

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

Get all scan workflow accesses

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule permission.

  • Path: /scan/access

  • Method: GET

  • Returns: list<ScanWorkflowAccessInfo>

  • Errors: 403, 404

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

Update scan workflow access

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule and ModifyScanWorkflowAccessRule permissions.

  • Path: /scan/access/<accessId>

  • Method: PUT

  • Parameters:

    • accessId: int Id of the workflow access

    • accessInfo: ScanWorkflowAccessInfo - see Data structures.

  • Returns: ScanWorkflowAccessInfo

  • Errors: 403, 404

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule and CreateScanWorkflowAccessRule permissions.

  • Path: /scan/access

  • Method: POST

  • Parameters:

  • Returns: ScanWorkflowTemplateInfo

  • Errors: 403, 404

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

Permission info

If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule and DeleteScanWorkflowAccessRule permissions.

  • Path: /scan/access/<accessId>

  • Method: DELETE

  • Parameters:

    • accessId: int Id of the workflow access

  • Returns: 204

  • Errors: 403, 404

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

Certificates

This API is not available on gateways.

Import a CA certificate

A ModifyCertificate permission is needed for this operation.

  • Path: /certificate/ca

  • Method: POST

  • Body: "application/octet-stream" of PEM/DER file

  • Returns: 200 and CertificateInfo structure which contains

    • alias

    • serial

    • subject

    • issuer

    • notBefore

    • notAfter

    • body (public part of the certificate)

  • Errors: 400

CODE 
curl -X POST -k -i -H X-Api-Key:$API_KEY -H Content-Type:application/octet-stream --data-binary "@cacert.pem" https://:7300/api/v1/certificate/ca

Import private certificate chain

A ModifyCertificate permission is needed for this operation.

  • Path: /certificate/chain

  • Method: POST

  • Body: "multipart/form-data" with two parts:

    • "password" part, which contains a keystore password (string)

    • "data" part, which contains binary stream of P12/PFX file

  • Returns: 200 and list of CertificateInfo structure which contains

    • alias

    • serial

    • subject

    • issuer

    • notBefore

    • notAfter

    • body (public part of the certificate)

  • Errors: 400

CODE 
curl -X POST -k -i -H X-Api-Key:$API_KEY -F data="@chain.p12" -F password=changeit https://:7300/api/v1/certificate/chain

Get a CA certificate

A ViewCertificate permission is needed for this operation.

  • Path: /certificate/ca

  • Method: GET

  • Optional query parameters (you can combine them):

    • subject (could be a substring)

    • serial (bigint)

    • alias (string)

    • issuer (string)

    • expiresin (int - number of days)

  • Returns: 200 and list of CertificateInfo structure which contains

    • alias

    • serial

    • subject

    • issuer

    • notBefore

    • notAfter

    • body (public part of the certificate)

  • Errors: 400

CODE 
curl -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/ca?serial=828286999265050717

Get private certificate chain

A ViewCertificate permission is needed for this operation.

  • Path: /certificate/chain

  • Method: GET

  • Optional query parameters (you can combine them):

    • subject (could be a substring)

    • serial (bigint)

    • alias (string)

    • issuer (string)

    • expiresin (int - number of days)

  • Returns: 200 and list of CertificateInfo structure which contains

    • alias

    • serial

    • subject

    • issuer

    • notBefore

    • notAfter

    • body (public part of the certificate)

  • Errors: 400

CODE 
curl -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/chain?subject=CA

Delete a CA certificate

A DeleteCertificate permission is needed for this operation.

  • Path: /certificate/ca/<alias>

  • Method: DELETE

  • Mandatory path parameter:

    • alias

  • Returns: 200 

  • Error codes: 1130, 1134

CODE 
curl -X DELETE -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/ca/imported-aeba53f2-78cf-4fad-b134-d61c5e940cdc

Delete private certificate chain

A DeleteCertificate permission is needed for this operation.

  • Path: /certificate/chain/<alias>

  • Method: DELETE

  • Mandatory path parameter:

    • alias

  • Returns: 200 

  • Error codes: 1131, 1135

CODE 
curl -X DELETE -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/chain/7c9c05e5-2622-4c9d-9f76-2c11a6d24846

Get root authorities

This endpoint returns root authorities only for self-signed certificates that were created using the "Create..." (Private certificate chains) button. Custom (external) chains that were imported will be ignored. The signing certificates are also ignored.

  • Path: /certificate/root

  • Method: GET

  • Returns: 200 and list of CertificateInfo structure which contains

    • alias

    • serial

    • subject

    • issuer

    • notBefore

    • notAfter

    • body (public part of the certificate encoded as base64 DER)

CODE 
curl -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/root

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close