iCONECT API Documentation 0.12.0 (v1)
Last updated: 2026-11-09
Required version of iCONECT: 13.5.17
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).
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.
Breaking Changes
- Authorization: The token endpoint now enforces client authentication. Confidential applications must send their
client_secreton every grant (authorization_code,refresh_token, andpassword), usingclient_secret_basicorclient_secret_post. Keep theclient_secretserver-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_secretmay 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 returnsunauthorized_client. Accounts that require multi-factor authentication (MFA) can no longer use this grant, and only theopenidandiconect_apiscopes are accepted. - Authorization: The
client_credentialsgrant is no longer supported.
Documentation
- Added
client_secretto the authorization code, refresh token, and password grant examples and parameters. Corrected the token-request example to usegrant_type=authorization_code, and removed an invalidgrant_typeparameter from the authorize-request example.
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_infofield 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_infofield 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_infoparameter to copy batch info metadata from the current batch to the next level batch.
New Endpoints
- Get - Batch Set Record IDs: retrieve record IDs for one or more batch sets, with optional filtering by batch status.
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).
New Features and Updates
- Added support for batching features, including batch management and batch set management endpoints.
New Endpoints
- Batch Sets: create, edit, and delete batch sets.
- Batches: create, assign, and delete batches.
- Get - Batch Set By ID: retrieve a batch set by its ID.
New Features and Updates
- Enhanced request and response payload documentation for all endpoints.
Modified or Updated Endpoints
- Add Records to Folder: The request body of this payload has been changed to accept an array of record IDs.
- Remove Records from Folder: The request body of this payload has been changed to accept an array of record IDs.
Bug Fixes
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
- Authorization Code Grant: This URI has been changed from
{iconectURL}/oauth/authorizetohttps://{identityURL}/openid/authorize. - Password Credentials Grant: This URI has been changed from
{iconectURL}/oauth/authorizetohttps://{identityURL}/openid/token. - Password Credentials Grant: A Client ID is now required when using this grant type.
- Refresh Code Grant: This URI has been changed from
{apiURL}/oauth/authorizetohttps://{identityURL}/openid/token. - Authorization: The
iconect_apiscope is now required.
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.
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
- Fixed an issue in the Password Credentials Grant flow where access token
expires_inwould differ from the actual token life time.
New Endpoints
- User: Access information about the authorized user
- Project - Project Settings: Access metadata about the settings configured for a project
- System Information: Access information about the iCONECT system and REST API
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.
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)
New Endpoints
- Views: create and manage views in a project
Modified or Updated Endpoints
- Jobs: Supported job types now include Delete Records
- Jobs: The start job endpoint has been modified to accept a request body when starting a Delete Records job Start Job
- Authorization: Support for OAuth Password Credentials Grants is now supported. See the Password Credentials Grant section for more details.
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
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-8are now permitted
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 foundcode when the object doesn't exist Authorization_codeflow was introduced to the OAuth authentication replacing thepasswordflow from Beta 1. See the Authorization section for more details on how the access and refresh token is retrieved.
New Endpoints
- Project - Update: changes a project’s name and description
- Fields - Delete: deletes fields in a project
- Fields by ID: retrieves Fields by ID
- Records - Update: Updates records in batches
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
projectsandtemplates. 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
fileparameter should be provided in the body of the request: See Files for details.
Bug Fixes
- The Panel
locationproperty 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
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.
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.
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 Code | Explanation | Description |
|---|---|---|
| 200 | OK | The request was completed |
| 201 | Created | The object was created |
| 400 | Bad Request | Incorrect request. Please check the parameters |
| 401 | Unauthorized | Access is not yet authorized |
| 403 | Forbidden | The endpoint is not available with the level of access |
| 404 | Not found | The object was not found |
| 415 | Unsupported Media Type | The request was sent with an incorrect media type |
| 500 | Internal Server Error | An internal server error has occurred |
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.
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:
- 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.
- Get authorization from the user
- Retrieve the access code and token
- Make Authenticated Requests with the token
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
| Parameter | Type | Explanation |
|---|---|---|
| client_id | string | The client_id provided by an iCONECT administrator |
| response_type | string | Must be 'code' |
| redirect_uri | string | Redirect_URI must match the URL registered with the external application in iCONECT v10 |
| state | string | A hash code used by the external application to validate iCONECT's response |
| code_challenge | string | A code computed using a unique code verifier and the specified hash method |
| code_challenge_method | string | Must be 'S256' |
| scope | string | The 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.
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
| Parameter | Type | Explanation |
|---|---|---|
| code | string | The code returned from the /openid/token endpoint. |
| client_id | string | The client_id provided by an iCONECT administrator. |
| client_secret | string | The client_secret provided by an iCONECT administrator. Required for confidential applications; not required for non-confidential applications. |
| grant_type | string | 'authorization_code' |
| redirect_uri | string | Redirect_URI must match the URL registered with the application in iCONECT. |
| code_verifier | string | The 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 Code | Explanation |
|---|---|
| 200 OK | JSON string with the access token |
| 400 Bad Request | Incorrect request. Please check the parameters |
| 401 Unauthorized | Missing, incorrectly formatted or invalid combination of parameters |
| 500 Server Error | An internal server error has occurred |
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
| Parameter | Type | Explanation |
|---|---|---|
| grant_type | string | 'refresh_token' |
| refresh_token | string | The refresh_token is provided with every token request. |
| client_id | string | The client_id provided by an iCONECT administrator. |
| client_secret | string | The 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 Code | Explanation |
|---|---|
| 200 OK | JSON string with the access token |
| 400 Bad Request | Incorrect request. Please check the parameters |
| 401 Unauthorized | Missing, incorrectly formatted or invalid combination of parameters |
| 500 Server Error | An internal server error has occurred |
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 \.
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'
}
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'
}
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 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
}
]
}
| Property | Required | Description |
|---|---|---|
key | Yes | Unique identifier for the field. Used programmatically by integrations and automation. Max 100 characters. |
value | Yes | The field value, always stored as a string. Max 100 characters. |
label | No | Human-readable display name shown in the UI. If omitted, the key is displayed instead. Max 100 characters. |
type | No | Determines how the UI formats the value. Defaults to plain text if omitted. See supported types below. |
visible | No | When 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. |
| Type | Value Format | UI Display |
|---|---|---|
string | Any text | Plain text |
number | Numeric (e.g. "12.5") | Formatted number |
date | ISO 8601 date (YYYY-MM-DD) | Locale-formatted date |
datetime | ISO 8601 with time (YYYY-MM-DDTHH:mm:ssZ) | Locale-formatted date and time |
boolean | "true" or "false" | Yes/No indicator |
url | Valid URL | Clickable link |
If type is omitted or not recognized, the value is displayed as plain text.
