How to configure API destination

API destination lets a workflow send scanned files to any HTTP or HTTPS endpoint.

It is designed for integrations where the target system expects:

• a direct file upload,

• a file upload together with additional fields or headers,

• one or more API calls before or after the upload,

• OAuth 2.0 or Basic authentication,

• user-specific values or user-specific credentials.

Unlike Dropbox, Google Drive, and similar destinations, user-specific API authorization is handled per workflow. In the Workplace, users see a separate item for each API workflow that requires private user data or private user authentication.

Typical Use Cases

Use API Delivery when you need one of these patterns:

• Upload a file to a custom DMS, ERP, CRM, or ticketing API.

• Send the file together with metadata fields such as document type, customer number, or job ID.

• Call one API to create a record, parse the returned ID, then use that ID in the upload call.

• Upload the file first and then call another API to confirm or finalize the transaction.

• Use one shared service account for all users.

• Use a separate OAuth token, Basic credentials, or business identifier for each user.

How API Delivery Works

API Delivery executes a sequence of HTTP requests for each delivered file.

The important rules are:

1. The workflow Destination field is the main Delivery URL.

2. The Requests area contains the Delivery request and any additional requests.

3. The requests run in the same order as the tabs are shown on screen.

4. The Delivery tab does not have to be last. You can place it before or after other requests.

5. Response values parsed from one request can be reused by later requests in the same sequence.

6. The whole sequence runs separately for each file.

7. Authentication settings are shared by the whole sequence. The same auth is used for all additional requests and for the Delivery request.

This means you can build flows such as:

1. Create record.

2. Read returned ID.

3. Upload file with that ID.

4. Confirm completion.

Settings Reference

User specific

Use the workflow User-specific option when the workflow should store private API data per user instead of only one shared configuration for the whole workflow.

For API Delivery, this can now be used for:

• user-specific OAuth,

• user-specific Basic authentication,

• user-specific custom values such as tenant ID, customer code, branch code, or target mailbox ID.

Revoke user-specific authorization on save

When editing an existing user-specific API workflow, a checkbox named Revoke user-specific authorization on save is shown near the Save button.

Use it when you want all currently saved private API authorizations for that workflow to be cleared after saving.

This is useful when you change:

• authentication behavior,

• parameter keys,

• endpoint logic,

• required user-specific values.

Authentication Settings

Authentication type

Available values:

• None

• Basic HTML authentication

• OAuth 2.0

This authentication is applied to all requests in the sequence, not only to the Delivery request.

None

Use this when the target API does not require authentication, or when access is handled by a static header you add manually in Request parameters.

Typical example:

• X-API-Key in the request header as a static custom value.

Basic HTML authentication

This is standard HTTP Basic authentication.

When selected, the workflow shows:

• Login

• Password

Use this when the API expects an Authorization: Basic ... in the header.

OAuth 2.0

When selected, the workflow shows:

• Authorization endpoint URL

• Token endpoint URL

• Client ID

• Client secret

• Scopes (space separated)

Use this when the API requires OAuth authorization code flow and refresh tokens.

User-specific authentication

This checkbox is visible only when all of these are true:

• The workflow is user-specific,

• Destination type is API,

• Authentication type is Basic HTML authentication or OAuth 2.0.

Behavior:

• If checked with OAuth 2.0, each user authorizes the workflow from Workplace.

• If checked with Basic HTML authentication, each user enters their private login and password in Workplace.

• If not checked, authentication remains shared on the workflow level.

Requests Area

The Requests area contains the complete request timeline for one delivered file.

The timeline contains:

• One Delivery tab,

• Zero or more additional Request tabs.

The order of the tabs is the execution order.

You can:

• Add new requests with Add request,

• Remove requests,

• Drag request tabs to change execution order.

Default behavior:

• Delivery usually starts as the last step,

• But you can move it earlier if the target API requires upload before a follow-up API call.

Delivery Tab Settings

Destination URL

This is the standard workflow Destination field outside the request tabs.

In API mode it becomes the main upload URL used by the Delivery request.

You can use parameter placeholders in the URL if needed.

Name of file form field

This is the form field name used for the uploaded file in multipart mode.

Default:

• file

Use it when the target API expects something else such as:

• document

• content

• attachment

• uploadedFile

Allowed characters should be simple field-name characters such as letters, numbers, ., _, and -.

Delivery method

Available values:

• POST

• PUT

Delivery body type

Available values:

• Multipart/form-data

• Raw body

Multipart/form-data

Use this when the API expects:

• the file plus extra fields,

• the file plus metadata,

• file upload as classic multipart form.

Raw body

Use this when the API expects the file stream as the whole request body.

In this mode:

• Only the file body is sent,

• Request headers are still applied,

• Form/body parameters are not sent,

• Metadata is not sent with the delivery request.

This is the correct option for endpoints such as direct binary PUT uploads.

Request parameters

These are parameters for the Delivery request itself.

Each row has:

• Key- Represents the key under which the parameter is used in the resulting request

• Value- Defines the source/value used in the generated request. The exact behavior depends on the parameter type.

• Type - Type of used request parameter (See detailed description below)

• Location - Determines where the parameter will be used in the resulting request

Parameter location

Location supports: Request header and Form/Body

Parameter type

Type supports: System parameter, Custom parameter, Terminal parameter, Response parameter, and User-specific parameter

System parameter

Use this when the value should come from OptimiDoc system parameters (placeholder formatting).

This is the same placeholder mechanism used in other workflow areas such as output filenames and formatted text fields.

You typically enter:

• a parameter name, or

• a placeholder such as [ParameterName].

Use this for values that already exist in the workflow context.

Custom parameter

Use this for a fixed literal value.

Examples:

• fixed API key,

• constant document type,

• constant source system name.

Terminal parameter

Use this when the value should come from the MFP terminal as placeholder data available in OptimiDoc.

This is resolved through the same placeholder engine as system parameters.

You typically enter:

• a terminal parameter key, or

• a placeholder such as [TerminalParameterKey].

Response parameter

Use this when you want to reference a value that was parsed earlier from a response (for details, see Response parameters section here).

User-specific parameter

Use this when the value must be entered separately by each user.

This type is visible only when the workflow is User-specific (See more details here).

For this type:

• Key is the internal parameter key used in requests and placeholders.

• Value is not the real parameter value. It is the label shown to the user in the Workplace pop-up.

Response parameters

These rows define how to parse values from the response. Values can be parsed from JSON or XML responses.

Each row has: Key and Value

Key is the variable name you want to create.

Value is the selector used to extract the returned value:

• simple JSON path such as data.id or items[0].id for array objects addressing,

• XPath (xml) such as /root/id.

Additional Request Settings

Each extra Request tab represents one API call in the sequence.

Request URL

This is the URL for that request. You can use placeholders in the URL.

Examples:

• https://api.example.com/jobs

• https://api.example.com/jobs/[jobId]/complete

• [baseUrl]/v1/documents

Request method

Available values: POST, GET, PUT, PATCH

Request body type

Available values: Form, JSON, None

JSON body source

Visible when Request body type is JSON.

Available values: From parameters and JSON editor

From parameters

The JSON body is generated from request parameters with the location value set to Form/Body.

Example of generated body from the set request parameters:

{
  "documentType": "[docType]",
  "customerId": "[customerId]",
  "workflow": "[workflow_name]"
}

JSON editor

You write the entire JSON request body manually in JSON body template.

Use placeholders directly in the template.

Example:

{
  "PropertyValues": [
    {
      "PropertyDef": 0,
      "TypedValue": {
        "DataType": 1,
        "Value": "[documentname]",
        "UploadID": [UploadID]
      }
    }
  ]
}

Request parameters

This table works the same way as the Delivery request parameter table. (See here)

Response parameters

This table works the same way as the Delivery response parameter table. (See here)

Metadata Export Integration

API Delivery can also send workflow metadata, but only when Metadata export is enabled in the workflow.

Workflow settings involved:

• Enable metadata export

• Export metadata in a form field

• Name of metadata form field

This is useful when the target API expects either:

• a separate JSON or XML metadata file, or

• a single form field containing metadata text.

Shared vs User-Specific Authorization

Shared Authentication

Typical use-cases:

• one company service account,

• one shared OAuth application token,

• one shared Basic account.

Shared Basic authentication

Configuration:

1. Set Authentication type to Basic HTML authentication.

2. Fill Login and Password.

3. Save the workflow.

Nothing else is needed. There is no separate authorization step.

Shared OAuth 2.0

Configuration:

1. Set Authentication type to OAuth 2.0.

2. Fill in the OAuth endpoints, client ID, client secret, and scopes.

3. Save the workflow.

4. Return to the workflow list.

5. Click the key icon on the workflow row.

6. Complete the provider authorization screen.

After that, the workflow is authorized for shared use.

User-Specific Authorization and User-Specific Data

Use user-specific mode when each user must deliver files with their own private API data.

Examples:

• each user has their own OAuth account,

• each user has their own Basic credentials,

• each user chooses a private destination code, such as department, mailbox, tenant, branch, or external user ID.

How users authorize in Workplace

Users go to:

1. Workplace

2. Private destinations

3. Click the API workflow item shown under the workflow name

The item is shown only when:

• The workflow is user-specific

• The workflow is API destination

• The user has rights to use the workflow

• The workflow requires private user configuration such as user-specific auth or user-specific parameters.

The status shows:

• Authorized

• Not authorized

What happens when the user clicks the item

If the workflow has user-specific parameters

A pop-up is shown with one input row per user-specific parameter.

The label of each row is taken from the parameter Value, which acts as the display label.

All fields are required.

If the workflow has user-specific Basic authentication

The same pop-up also includes:

• Login

• Password

All fields are required.

If the workflow has user-specific OAuth

There are two possible behaviors:

• If the workflow also has user-specific parameters, the pop-up with parameters is shown first, and then the user is redirected to OAuth,

• If the workflow only needs OAuth and no parameter pop-up input is required, the user is redirected directly.

• 
  

Recommended Setup Patterns

Use Case 1: Simple file upload without authentication

Use this when the endpoint only needs a file upload.

Setup:

1. Authentication type = None

2. Delivery method = POST

3. Delivery body type = Multipart/form-data

4. Set the file field name if the API expects a name other than file

Good for:

• simple inbound upload endpoints,

• test endpoints,

• internal services behind network trust.

Use Case 2: Upload with a static API key header

Use this when the endpoint expects a custom header such as X-API-Key.

Setup:

1. Authentication type = None

2. In Delivery Request parameters, add: Key = X-API-Key Value = your-real-api-key Type = Custom parameter Location = Request header

Good for:

• APIs that do not use OAuth or Basic auth,

• API gateway style integrations.

Use Case 3: Shared Basic authentication

Use this when one shared account is enough for the whole workflow.

Setup:

1. Authentication type = Basic html authentication

2. Fill Login and Password

3. Save the workflow

Good for:

• one shared service account,

• simple internal REST endpoints.

Use Case 4: Shared OAuth 2.0

Use this when one shared OAuth authorization should be used for all workflow users.

Setup:

1. Authentication type = OAuth 2.0

2. Fill OAuth settings

3. Save workflow

4. Authorize it from the workflow list using the key icon

Good for:

• one central integration account,

• one tenant-wide service authorization.

Use Case 5: User-specific OAuth 2.0

Use this when each user must deliver with their own OAuth account.

Setup:

1. Turn on workflow User specific

2. Set Authentication type = OAuth 2.0

3. Check User specific authentication

4. Save the workflow

5. Each user authorizes the workflow in Workplace

Good for:

• each user sends to their own external account,

• delivery must be audited under the user identity,

• the API requires user consent per person.

Use Case 6: User-specific Basic authentication

Use this when each user has their own Basic credentials.

Setup:

1. Turn on workflow User specific

2. Set Authentication type = Basic html authentication

3. Check User specific authentication

4. Save the workflow

5. Each user enters their own login and password in Workplace

Good for:

• legacy APIs with per-user service credentials,

• systems that do not support OAuth but must keep user accounts separate.

Use Case 7: Shared authentication plus user-specific business value

Use this when all users share the same technical auth, but each user must send a different business value.

Example:

• shared OAuth token,

• each user must send their own customerCode.

Setup:

1. Turn on workflow User specific

2. Keep authentication shared, or use shared OAuth/Basic

3. Add a Delivery or Request parameter: Key = customerCode Value = Customer code Type = User specific parameter Location = Form/Body or Request header

4. Save the workflow

5. Each user fills Customer code in Workplace

Good for:

• shared integration account with per-user routing,

• branch-based or department-based external routing.

Use Case 8: Create a record first, then upload the file

Use this when the target API requires a record ID before the upload call.

Example flow:

1. Request 1 creates the external record.

2. Request 1 response parameter parses jobId from data.id.

3. Delivery uses jobId in the URL, headers, or form/body.

Example:

Request 1

• URL: https://api.example.com/jobs

• Method: POST

• Body type: JSON

• JSON template:

{
  "workflow": "[workflow_name]",
  "user": "[username]"
}

Request 1 response parameters

• Key = jobId

• Value = data.id

Delivery

• Destination URL: https://api.example.com/jobs/[jobId]/documents

Good for:

• ticket-based APIs,

• DMS platforms that require a document container first.

Use Case 9: Upload file first, then confirm or finalize

Use this when the upload response must be parsed and used in a later request.

Example flow:

1. Move Delivery before Request 2

2. Parse uploadId from the Delivery response

3. Use uploadId in Request 2

Example:

Delivery response parameters

• Key = uploadId

• Value = data.uploadId

Request 2

• URL: https://api.example.com/uploads/[uploadId]/complete

• Method: PATCH

Good for:

• APIs with asynchronous upload finalization,

• systems that need explicit completion after file transfer.

Use Case 10: Raw binary upload

Use this when the endpoint expects the file as the whole request body.

Setup:

1. Delivery method = PUT or POST

2. Delivery body type = Raw body

3. Put any required auth or custom headers in Delivery request parameters

Important:

• do not rely on form/body parameters here,

• do not rely on metadata attachment here,

• if the target system also needs metadata, send it through an additional request.

Best Practices

1. Start with the smallest possible working request sequence.

2. Use Multipart/form-data unless the API clearly expects the raw file body.

3. Use additional requests only when the target API really requires them.

4. Use response parameter keys with simple names such as jobId, uploadId, folderId.

5. Keep header names simple and standard.

6. Use Custom parameter for fixed literal values.

7. Use System parameter, Terminal parameter, or Response parameter only when you really need placeholder resolution.

8. Use User specific parameter when the real value must come from the user.

9. If you change the user-specific contract of a live workflow, use Revoke user-specific authorization on save.

10. If the target system expects JSON, prefer JSON editor when the body structure is nested or complex.

Troubleshooting

The file is uploaded, but additional fields are missing

Check:

• Delivery body type is not Raw body

• The fields are placed in Form/Body

• The endpoint really expects multipart fields

The request body is JSON, but my request parameters are ignored

If JSON body source = JSON editor, the JSON template becomes the whole body.

Only header parameters are used in request.

My later request does not see a parsed value

Check:

• The earlier request really runs first

• The response selector is correct

• The response is JSON or XML in the format you expect

• The later request uses Type = Response parameter

User-specific API workflow is shown as Not authorized

Check whether the workflow requires one or more of these:

• user-specific OAuth,

• user-specific Basic credentials,

• user-specific parameters.

The workflow is considered authorized only when all required private values for that user are saved.

OAuth is configured, but delivery still fails

Check:

• The workflow was actually authorized after saving

• The token endpoint and authorization endpoint are correct

• The scopes are correct

• The provider supports authorization code flow and refresh token exchange for this client

Request URL validation fails

Check:

• The URL contains no whitespace

• The URL contains a scheme such as https://

• The full URL is created from placeholders