iCONECT API Documentation 0.12.0 (v1)

Last updated: 2026-11-09

Required version of iCONECT: 13.5.17

Introduction

The iCONECT API allows developers to work with objects in iCONECT, including advanced functionality like managing clients, projects, records and files, using OpenID Connect authentication. This API uses common RESTful verbs, like GET, POST, PUT, and DELETE requests with JSON arguments and responses. Use this documentation to start making API calls.

The iCONECT API is a set of stateless services that uses endpoints to manage the following objects:

  • Clients: create, manage, and retrieve project association
  • Projects: create, manage, assign to a client and retrieve client association
  • Fields: create and manage fields in a project
  • Panels: create and manage panels in a project
  • Folders: create, manage, and assign to panels or parent folders
  • Records: create, manage, and assign to folders
  • Upload native files: manage the files linked to a record
  • Jobs: manage jobs in a project
  • Views: create and manage views in a project
  • File Stores: access file stores in a project
  • Templates: access templates in a project
  • Batch Sets: create, update, delete, and retrieve batch sets in a project
  • Batches: create and manage batches in a project. This includes all aspects of batch creation and management, such as batch assignment, batch status, and user-defined metadata (batch info).

Release Notes

Use these notes to review the latest iCONECT API and documentation updates. This section lists API operations and fields that were added, changed, or removed.

Changes in Beta 15

Breaking Changes

  • Authorization: The token endpoint now enforces client authentication. Confidential applications must send their client_secret on every grant (authorization_code, refresh_token, and password), using client_secret_basic or client_secret_post. Keep the client_secret server-side only - never embed it in browser (SPA), mobile, or desktop applications; register those as non-confidential applications instead. Non-confidential applications are not required to send a secret and should protect the authorization code flow with PKCE (enable Require PKCE on the application).
  • Password Credentials Grant: A confidential client that sends its client_secret may use this grant. A non-confidential client may use it only if a system administrator enables it for that client ID in the Identity Provider's server configuration; otherwise the token endpoint returns unauthorized_client. Accounts that require multi-factor authentication (MFA) can no longer use this grant, and only the openid and iconect_api scopes are accepted.
  • Authorization: The client_credentials grant is no longer supported.

Documentation

  • Added client_secret to the authorization code, refresh token, and password grant examples and parameters. Corrected the token-request example to use grant_type=authorization_code, and removed an invalid grant_type parameter from the authorize-request example.

Changes in Beta 14

New Features and Updates

  • Added support for user-defined batch metadata (Batch Info). Batches can now carry custom JSON fields that are displayed on the batch card in the UI or used as machine-readable metadata for automation and integrations.

New Documentation

  • Batch Info Schema: new documentation section describing the JSON structure, supported field types, validation rules, and limits for batch metadata.

Modified or Updated Endpoints

  • The Batches - Create endpoint now accepts an optional batch_info field containing user-defined metadata following the Batch Info Schema. In the end user interface, this functionality is license controlled. Contact iCONECT Support for details.
  • The Batches - Update endpoint now accepts a batch_info field to update or clear batch metadata. Set to an empty string to clear existing info, or omit to leave unchanged.
  • The Batches - CheckIn endpoint now supports a copy_batch_info parameter to copy batch info metadata from the current batch to the next level batch.

Changes in Beta 13

New Endpoints

Modified or Updated Endpoints

  • The Batches - CheckIn endpoint has been updated so that you can copy notes from a checked-in batch to its counterpart in the next generation batch set.
  • The Batches - Assign endpoint has been updated to accept a user ID, name, or email.
  • The Jobs endpoints now support creating and managing metadata overlay jobs (type 50008 / MatchMask).

Changes in Beta 12

New Features and Updates

  • Added support for batching features, including batch management and batch set management endpoints.

New Endpoints

Changes in Beta 11

New Features and Updates

  • Enhanced request and response payload documentation for all endpoints.

Modified or Updated Endpoints

Bug Fixes

  • Corrected a missing scope parameter for the Authorization Code Grant and Password Credentials Grant sections.
  • Corrected erroneous request and response payloads in Records, Folders, Panels, and Fields endpoints.

Changes in Beta 10

New Features and Updates

  • The REST API is now running on ASP.NET Core 6.0.
  • Documentation is now automatically updated with each build.
  • The REST API now authenticates with the iCONECT Identity Provider using OpenID Connect.

Breaking Changes

Modified or Updated Endpoints

  • Authorization: The REST API now uses OpenID Connect for authentication and authorization. The API access tokens are now in the form of a JSON Web Token (JWT) that is signed by the primary web UI instance.
  • Authorization: Password Grant will no longer issue a refresh token. It is advised to transition any Password Grant flows to different authentication.

Bug Fixes

  • Folders by ID: Added missing documentation for this endpoint.
  • Record Count: Added missing documentation for this endpoint.
  • Folders for Record: Added missing documentation for this endpoint.
  • Multiple corrections to the naming of enums, including brief descriptions of each value.

Changes in Beta 9

New Endpoints

  • Upload Target: Retrieves the project ID that has been configured in iCONECT for uploading data to.

Modified or Updated Endpoints

  • File Store Upload: The File Stores endpoint now supports functionality to upload files directly.
  • Authorization: Password Credentials Grant now issues a refresh token. See the Password Credentials Grant section for more details.
  • Create Records:
    • The Create Records endpoint now additionally supports adding references to Amazon S3 Buckets as native files.
    • The Create Records endpoint now returns more detailed error reporting.
  • Update Records: The Update Records endpoint now additionally supports adding references to Amazon S3 Buckets as native files.

Bug Fixes

Changes in Beta 8

New Endpoints

Modified or Updated Endpoints

  • Authorization: Proof Key for Code Exchange (PKCE) is now required when using the Authorization Code flow.

Bug Fixes

  • Fixed an issue in File Upload where users would not be able to upload a file in some cases.

Changes in Beta 7

  • This version did not have any API interface changes

Changes in Beta 6

New Endpoints

  • Templates: Access Native Import template objects in a project

Modified or Updated Endpoints

  • Jobs: Supported job types now include Native Imports
  • Records - List: Records List can now optionally accept a View ID
  • File - Upload: Improved performance when uploading a file in a single request (or chunk)

Changes in Beta 5

New Endpoints

  • Views: create and manage views in a project

Modified or Updated Endpoints

Changes in Beta 4

Modified or Updated Endpoints

  • Error handling for the update records endpoint was adjusted. If there is an issue on one record passed in, all other records will still be updated. A 200 response will be returned along with an array that lists the specific records that could not be updated: Records - Update

Changes in Beta 3

New Endpoints

  • Jobs: manage jobs in a project
  • File Stores: access file store objects in a project

Modified or Updated Endpoints

  • The endpoint to upload a file now includes support for large files, with the ability to use chunked uploads. This endpoint now also requires the set up of a Native File Upload File Store for the project. See File - Upload
  • Error handling for the update records endpoint was adjusted. If there is an issue on one record passed in, all other records will still be updated. The returned error will contain information for every failure that happened during the update: Records - Update

Bug Fixes

  • Requests with the content type application/json; charset=utf-8 are now permitted

Changes in Beta 2

New Features and Updates

  • This iCONECT REST API is in a new format .
  • All endpoints return more specific codes. See Response Codes for details.
  • Endpoints that query objects by ID now return 404 - Not found code when the object doesn't exist
  • Authorization_code flow was introduced to the OAuth authentication replacing the password flow from Beta 1. See the Authorization section for more details on how the access and refresh token is retrieved.

New Endpoints

Modified or Updated Endpoints

  • The endpoint to deactivate a Client is renamed to /clients/:id/deactivate: Client - Deactivate
  • The endpoint to deactivate a Project is renamed to /projects/:id/deactivate: Project - Deactivate
  • The project list endpoint now allows filtering projects and templates. See Project List for more details
  • Null and empty fields are now handled and validated when creating or updating records: Records - Update
  • Files: parameters are now provided in the path. Only the file parameter should be provided in the body of the request: See Files for details.

Bug Fixes

  • The Panel location property description was updated to the correct enum: Panel - Create
  • The create records endpoint now returns all successfully create records: Records - Create
  • Fixed an issue where querying a record by ID returned a list instead of a single record
  • Fixed an issue where querying an empty folder returned records
  • Fixed an issue where querying a folder by ID returned a list instead of a single folder
  • Fixed an issue where updating multiple records that contained an invalid record could cause a failure to update all records

Terms of Use

The material in this document is the sole and exclusive intellectual property or iCONECT Development, LLC and/or iCONECT Worldwide Inc. Collectively (“iCONECT”). ICONECT believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided “as is”. ICONECT makes no representation or warranties of any kind with respect to the information in this publication and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Using, copying, and distribution of any ICONECT software described in this publication requires an applicable software license which is available by contacting info@iconect.com .

The information in this document is provided for use with ICONECT products. No licence, express or implied, to any intellectual property associated with this document or such products is granted by this document.

All ICONECT products described in this document are owned by ICONECT (or those companies that have licensed technology to ICONECT) and are protected by patents, trade secrets, copyrights or other industrial property rights worldwide.

The ICONECT products described in this document may still be in development. The final form of each product and release date thereof is at the sole and absolute discretion of ICONECT. Your purchase, license and/or use of ICONECT products shall be subject to ICONECT’s then current sales terms and conditions.

Downloading and/or use of any component herein confirms your agreement with these Terms of Use and you agree to be bound by these Terms of Use without signature.

Product Support

If you need more information about using the iCONECT API, contact iCONECT Support at (855) 915-8888 (non-US +1 519-645-6190) or email support@iconect.com.

Response Codes

The iCONECT API uses standard REST response status codes to indicate the success or failure of the calls.

The body of the response will be JSON in the following format for errors:

  { "iconect_error": "message" }

And for success codes:

  { "iconect_ok": "message" } 

The response code will be included in the header of the response and can be one of the following:

Response CodeExplanationDescription
200OKThe request was completed
201CreatedThe object was created
400Bad RequestIncorrect request. Please check the parameters
401UnauthorizedAccess is not yet authorized
403ForbiddenThe endpoint is not available with the level of access
404Not foundThe object was not found
415Unsupported Media TypeThe request was sent with an incorrect media type
500Internal Server ErrorAn internal server error has occurred

Authorization

The iCONECT Rest API supports OpenID Connect authenication and authorization.

The authorization code grant permits external application access to the API, which acts on behalf of the authorizing user and is the recommended flow. An external application must be registered with iCONECT before it can use OpenID Connect to authenticate users using the authorization code grant.

The password credentials grant is only recommended when a single user will act on behalf of a 3rd party application.

Authorization Code Grant

Administrators can create, and Users need to authorize access of external applications to the API. Before this can be done you need to ensure the external applications are authorized to access the API. You can revoke the access to the authorized application at any time.

Authorizing via OIDC requires the following steps:

  1. Create the application in iCONECT
    • Register for a new application. Log into iCONECT using your Administrator account.
    • Open Administration. The application menu will be displayed in the left sidebar.
    • Click New Application. This button can be found in the top right corner of the page.
    • Enter the name of the application and its redirect URI. If this application is a web UI, consider adding a Logout Redirect URI. Click Create.
    • Once the application is created go to the Application page and click on its name to get the client ID and client secret key.
  2. Get authorization from the user
  3. Retrieve the access code and token
  4. Make Authenticated Requests with the token

Obtaining an Authentication Code

The application accessing the Rest API needs to be registered on iCONECT v10. Administrators can provide the client_id and client_secret to the external application after it is created in iCONECT.

The external application can obtain an access code (to get the access token) sending a GET request to:

https://{identityURL}/openid/authorize
ParameterTypeExplanation
client_idstringThe client_id provided by an iCONECT administrator
response_typestringMust be 'code'
redirect_uristringRedirect_URI must match the URL registered with the external application in iCONECT v10
statestringA hash code used by the external application to validate iCONECT's response
code_challengestringA code computed using a unique code verifier and the specified hash method
code_challenge_methodstringMust be 'S256'
scopestringThe scope of the access request. The iconect_api and openid scopes are required.

Once completed, an iCONECT authorization page displays. If the external application is authorized, iCONECT sends the authorization code to the redirect_uri.

Getting Access Token with Authentication Code

The external application can request an access token using the code obtained from the https://{identityURL}/openid/authorize endpoint along with the other parameters provided, sending a POST request to:

https://{identityURL}/openid/token
ParameterTypeExplanation
codestringThe code returned from the /openid/token endpoint.
client_idstringThe client_id provided by an iCONECT administrator.
client_secretstringThe client_secret provided by an iCONECT administrator. Required for confidential applications; not required for non-confidential applications.
grant_typestring'authorization_code'
redirect_uristringRedirect_URI must match the URL registered with the application in iCONECT.
code_verifierstringThe string used to generate the code_challenge above.

If the response is successful, you are returned with a JSON string that contains the access, refresh tokens, and the expiry time in seconds.

Note: Once a refresh token has been used to acquire a new access token, it is considered to be consumed and is no longer valid.\

{
     'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
     'token_type': 'bearer',
     'expires_in': 3559,
     'refresh_token': 't3f389yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

The external application can obtain access to the Rest API points using the token provided.

Response CodeExplanation
200 OKJSON string with the access token
400 Bad RequestIncorrect request. Please check the parameters
401 UnauthorizedMissing, incorrectly formatted or invalid combination of parameters
500 Server ErrorAn internal server error has occurred

Getting Access Token with Refresh Token

The external application can request the access token using the refresh_token obtained from the https://{identityURL}/openid/token endpoint along with the other parameters provided, sending a POST request to:

https://{identityURL}/openid/token
ParameterTypeExplanation
grant_typestring'refresh_token'
refresh_tokenstringThe refresh_token is provided with every token request.
client_idstringThe client_id provided by an iCONECT administrator.
client_secretstringThe client_secret provided by an iCONECT administrator. Required for confidential applications; not required for non-confidential applications.

If the response is successful, you are returned with a a JSON string that contains the access, refresh tokens, and the expiry time in seconds:

{
     'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
     'token_type': 'bearer',
     'expires_in': 3559
}

The external application can obtain access to the Rest API points using the token provided.

Response CodeExplanation
200 OKJSON string with the access token
400 Bad RequestIncorrect request. Please check the parameters
401 UnauthorizedMissing, incorrectly formatted or invalid combination of parameters
500 Server ErrorAn internal server error has occurred

Authorization flow

1. Request authorization code

To request the authorization code, redirect the user to the https://{identityURL}/openid/authorize endpoint with the following GET parameters:

https://{identityURL}/openid/authorize?
    client_id=APP_ID&
    redirect_uri=REDIRECT_URI&
    response_type=code&
    state=YOUR_UNIQUE_STATE_HASH
    code_challenge=YOUR_UNIQUELY_GENERATED_HASH
    code_challenge_method=S256&
    scope=iconect_api%20openid
        

This will open the iCONECT login page to approve the application's access to their account and then redirect back to REDIRECT_URI that you provided. The redirect will includes a code parameter. For example if the REDIRECT_URI is https://mywebapp.com/oauth/redirect then the redirected URL will be:

https://mywebapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH

Use this code to request an access token. Note that: https is required and the REDIRECT_URI given in the request must be the same as the URI that is used when registering the application. For example https://mywebapp.com is not the same as https://mywebapp.com/ do not match because there is an extra \.

2. Request access token with authorization code

Once you have the authorization code you can request an access_token using any HTTP client. In the following example, we are using Java's Unirest library:

HttpResponse<String> response = Unirest.post("https://{identityURL}/openid/token")
.header("Content-Type", "application/x-www-form-urlencoded")
.field("client_id", "{client_id}")
.field("client_secret", "{client_secret}")
.field("code", "{code}")
.field("redirect_uri", "{wwww}")
.field("grant_type", "authorization_code")
.field("code_verifier", "{pkce_code_verifier}")
.field("scope", "iconect_api openid")
.asString();

Note: client_secret is required for confidential applications and is not required for non-confidential applications. Keep the client_secret server-side only - never embed it in browser, mobile, or desktop applications.

Example response:

{
   'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
   'token_type': 'bearer',
   'expires_in': 7200,
   'refresh_token': 't3f389yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

3. Request access token with refresh token

Since the access token is set to expire you can request for a new access token using the refresh_token using any HTTP client. In the following example, we are using Java's Unirest library:

HttpResponse<String> response = Unirest.post("https://{identityURL}/openid/token")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .field("client_id", "{client_id}")
    .field("client_secret", "{client_secret}")
    .field("refresh_token", "{refresh_token}")
    .field("grant_type", "refresh_token")
    .asString();

Note: client_secret is required for confidential applications and is not required for non-confidential applications.

Note: Each refresh returns a new refresh_token. Store it in place of the previous one - the old refresh_token stops working after it is used.

Example response:

{
    'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
    'token_type': 'bearer',
    'expires_in': 3559,
    'refresh_token': 'n3w742yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

Password Credentials Grant

The Password Credentials Grant allows a 3rd party application to authenticate by providing the username and password for a single user that will perform all API Actions. An OAuth request is made providing the credentials.

A single request is made to obtain an access token which is then used as a bearer token for further requests.

Note: A confidential client (one with a client secret) may use this grant. A non-confidential client may use it only if a system administrator has enabled it for that client ID in the Identity Provider's server configuration; otherwise the token endpoint returns unauthorized_client. Send the client_secret with every request. Accounts that require multi-factor authentication (MFA) cannot use this grant and receive the same invalid_grant error as invalid credentials - use the Authorization Code grant for those accounts. Only the openid and iconect_api scopes are allowed.

In the following example, we are using Java's Unirest library:

HttpResponse<String> response = Unirest.post("https://{identityURL}/openid/token")
.header("Content-Type", "application/x-www-form-urlencoded")
.field("grant_type", "password")
.field("username", "jsmith")
.field("password", "Password1234")
.field("client_id", "{client_id}")
.field("client_secret", "{client_secret}")
.field("scope", "iconect_api openid")
.asString();

Example response:

{
    'access_token': 'dh2389yhf93h28f38fg239rf3g2f9823hf23fh2398f4',
    'token_type': 'bearer',
    'expires_in': 3559,
    'refresh_token': 't3f389yhf93h28f38fg239rf3g2f9823hf23fh2398f4'
}

Batch Info Schema

Batch Info allows attaching custom metadata to individual batches as a JSON string. Each batch can carry a set of user-defined fields that are either displayed on the batch card in the UI (visible fields) or used as machine-readable metadata for automation and integrations (hidden fields).

The batch_info / sBatchInfo value is a JSON string containing a fields array. Each entry represents one metadata field.

Example:

{
  "fields": [
    {
      "key": "request_date",
      "label": "Request Date",
      "type": "date",
      "value": "2024-01-02",
      "visible": true
    },
    {
      "key": "claim_id",
      "label": "Claim ID",
      "value": "2423452345555",
      "visible": true
    },
    {
      "key": "veteran_file_number",
      "label": "Veteran File #",
      "value": "5678567856785",
      "visible": true
    }
  ]
}

Field Properties

PropertyRequiredDescription
keyYesUnique identifier for the field. Used programmatically by integrations and automation. Max 100 characters.
valueYesThe field value, always stored as a string. Max 100 characters.
labelNoHuman-readable display name shown in the UI. If omitted, the key is displayed instead. Max 100 characters.
typeNoDetermines how the UI formats the value. Defaults to plain text if omitted. See supported types below.
visibleNoWhen true, the field appears on the batch card in the UI. When false or omitted, the field is hidden from the UI but remains accessible via the API.

Supported Types

TypeValue FormatUI Display
stringAny textPlain text
numberNumeric (e.g. "12.5")Formatted number
dateISO 8601 date (YYYY-MM-DD)Locale-formatted date
datetimeISO 8601 with time (YYYY-MM-DDTHH:mm:ssZ)Locale-formatted date and time
boolean"true" or "false"Yes/No indicator
urlValid URLClickable link

If type is omitted or not recognized, the value is displayed as plain text.

Limits

ConstraintLimit
Maximum visible fields20
Maximum key length100 characters
Maximum value length100 characters
Maximum label length100 characters
Total JSON size2000 characters
Duplicate keysNot allowed
Servers
iCONECT REST API Route
https://{apiURL}