-
Getting started with Aico
- Logging into Aico for the First Time
- Creating your first journal
- Creating your first request
- Creating your first payment
- Creating your first Intercompany Invoice
- Working with Closing Tasks
-
Working with Journals
- An overview of Aico journals
- How to create a manual journal
- Create a journal by copying existing journals
- Import new journals from Excel
- How to import multiple journals from one Excel spreadsheet
- What are recurring journal entries?
- How to create Recurring Duplicate Journal entries
- How to create Recurring Allocation journal entries
- Create recurring journals with automatic reversals
- Reversing documents
- Import data to existing journals
- Working with Reconciliations
- Universal Settings
- Dashboards
- Closing Tasks
-
System Manager
-
Users and User Groups
- Overview of Users and User Groups
- Add user accounts
- Edit user account data
- Manage user groups
- Manage user roles
- Copying roles at the company level
- Copy user roles from individual users
- Create a user report
- Manage administrative user rights
- Super user mode
- Additional super user global admin rights
- User and User group export and import
- Value sets
- Currency Amount Groups
- Mail notifications
- Tax codes
- Maintenance
- Periods
- Companies
- Archiving
- Managing PDFs
-
Users and User Groups
-
Automation Manager
- Introducing Automation Manager
- Core Set Up
-
Task Templates
- Introducing task templates
- Creating task template details
- The Aico Document
- Aico document headers
- Preparer and Approver workflow settings
- Overriding parameters at a company level
- Master data export and import
- Set a custom schedule
- Dependent tasks in Aico
- How to use Smart tags in Aico
- How to add an attachment to a task template
- How to create a preparer start time
- Cross company dependent tasks
- Related link types
- Task Generation
- Companies
- Administrative tasks
- Staging API
-
Aico Announcements
-
Announcements
- Public holiday dates 2025: Aico Support Unavailable.
- NEW: Journal Entry Automation Deep Dive
- Aico Skills Lab: Journal Entry Configurations Tricks & Tips (Rescheduled)
- NEW: Aico Skills Lab Tips & tricks for Aico Journal Entries configuration
- NEW: Account Reconciliation Skills Lab Exclusively for Super Users!
- Public holiday dates 2024: Aico Support Unavailable.
- NEW: Software Release Presentation: Enhancing User Experience 24.1
- Public holiday dates 2023: Aico Support Unavailable.
- Release notes
- Maintenance Schedule
- Support Alerts
-
Announcements
- Aico Reviews
API functionality and methods
Modified on Tue, 4 Mar at 9:19 AM
The staging API allows the caller to
- Get list of available clients configured in the Aico system
- Get list of available companies configured in the Aico system
- Get list of document templates for a specific client. For each document template, it returns a list of which staging API header and row fields are available
- Get list of batches for a specific client
- Get list of documents in a specific batch
- Create a new batch for a client
- Add document(s) to a batch
- Close a batch
The first 5 methods (get list of clients/companies/document templates/batches/documents within a batch) exist for the client developer to get information about the configuration of the Aico system. This helps the developer understand the mapping of the API fields to the Aico document template fields.
The rest of the methods are for storing new staging documents and possibly doing error handling as well. Storing new documents can happen in one of two ways:
- Create a new batch and immediately include all the documents and their data in a single call.
- Create a batch without documents, add documents one-by-one in a loop, and then close the batch once all documents have been added.
- Create an empty batch in the Open state
- In a loop, add all documents that should go into the batch
- Close the batch, thereby marking it as Closed which will also indicate to Aico that the batch can be processed.
API methods
Verb | Path | Description |
GET | /staging/clients | Get list of available clients configured in the Aico system |
GET | /staging/companies | Get list of available companies configured in the Aico system |
GET | /staging/clients/{clientId}/document-templates | Get list of document templates for a specific client. Document templates list what staging API header and row fields are available |
GET | /staging/clients/{clientId}/batches | Get list of batches for a specific client. |
GET | /staging/batches/{batchId}/documents | Get list of documents in a specific batch |
POST | /staging/clients/{clientId}/batches | Create a new batch for a specific client. If the request is sent without documents then it will simply open the batch and return the batch Id. If the request is sent with documents then the batch is opened, the documents added and then automatically closed. |
POST | /staging/documents | Add a document to a specific batch |
PATCH | /staging/batches/{batchId}/close | Close a specific batch changing it from Open to Closed status |
Examples
Get list of clients
This call inspects available clients so that the caller can select the correct one for next calls.
Request URL: https://localhost:7060/staging/clients
Curl: curl -X 'GET' \
'https://localhost:7060/staging/clients' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {token}'
Response headers:
cache-control: no-store
content-security-policy: frame-ancestors 'none'
content-type: application/json; charset=utf-8
date: Mon,28 Oct 2024 08:14:24 GMT
server: Kestrel
strict-transport-security: max-age=2592000; includeSubDomains
x-content-type-options: nosniff
Response code: 200
Response body:
[
{
"id": 1,
"name": "Shared Client 1",
"contactPersonEMails": null,
"active": true,
"invalidDocumentsAllowed": true,
"retryAllowed": true,
"defaultCompanyCode": null,
"defaultDocumentTemplateCode": "StagingDT1"
},
{
"id": 2,
"name": "Shared Client 2",
"contactPersonEMails": null,
"active": true,
"invalidDocumentsAllowed": true,
"retryAllowed": true,
"defaultCompanyCode": null,
"defaultDocumentTemplateCode": "StagingDT1"
},
{
"id": 3,
"name": "Shared Client 3",
"contactPersonEMails": null,
"active": false,
"invalidDocumentsAllowed": false,
"retryAllowed": false,
"defaultCompanyCode": null,
"defaultDocumentTemplateCode": null
}
]
Here we get a list of staging header and row fields that are in use and which Aico document template fields they map to. Typically this method is called only during design-time by the customer, when the customer needs to implement their own integration code.
Request URL: https://localhost:7060/staging/clients/1/document-templates
Curl: curl -X 'GET' \
'https://localhost:7060/staging/clients/1/document-templates' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {token}'
Response headers:
cache-control: no-store
content-security-policy: frame-ancestors 'none'
content-type: application/json; charset=utf-8
date: Mon,28 Oct 2024 08:16:19 GMT
server: Kestrel
strict-transport-security: max-age=2592000; includeSubDomains
x-content-type-options: nosniff
Response code: 200
Response body:
[
{
"code": "StagingDT1",
"name": "Staging 1",
"description": null,
"headerFields": [
{
"stagingFieldName": "Text01",
"aicoFieldName": "Test textHeader1",
"aicoFieldInternalName": "textHeader1"
},
{
"stagingFieldName": "Text01",
"aicoFieldName": "Test textHeader2",
"aicoFieldInternalName": "textHeader2"
}
],
"rowFields": [
{
"stagingFieldName": "Text01",
"aicoFieldName": "Test textColumn2",
"aicoFieldInternalName": "textColumn2"
}
]
}
]
This call creates a new staging batch for a specific client. If no documents are given, then the batch will stay open and separate calls to the API are needed in order to add documents to the batch.
Request JSON body:
{
"note": "Batch created from a special source",
"externalId": "123",
"validateOnly": false
}
Request URL: https://localhost:7060/staging/clients/1/batches
Curl: curl -X 'POST' \
'https://localhost:7060/staging/clients/1/batches' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-d '{
"note": "Batch created from a special source",
"externalId": "123",
"validateOnly": false
}'
Response headers:
cache-control: no-store
content-security-policy: frame-ancestors 'none'
content-type: application/json; charset=utf-8
date: Mon,28 Oct 2024 08:20:34 GMT
server: Kestrel
strict-transport-security: max-age=2592000; includeSubDomains
x-content-type-options: nosniff
Response code: 200
Response body: 6
This call adds documents to the already existing and Open batch.
Request JSON body:
[
{
"batchId": 6,
"companyCode": "MYCOMPANY",
"documentTemplateCode": "StagingDT1",
"externalId": "1234",
"comments": "Some comments",
"text01": "My textHeader1 and textHeader2 value",
"rows": [
{
"lineNumber": 0,
"text01": "My textColumn2 value"
}
]
}
]
Request URL: https://localhost:7060/staging/documents
Curl: curl -X 'POST' \
'https://localhost:7060/staging/documents' \
-H 'accept: */*' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-d '[
{
"batchId": 6,
"companyCode": "MYCOMPANY",
"documentTemplateCode": "StagingDT1",
"externalId": "1234",
"comments": "Some comments",
"text01": "My textHeader1 and textHeader2 value",
"rows": [
{
"lineNumber": 0,
"text01": "My textColumn2 value"
}
]
}
]'
Response headers:
cache-control: no-store
content-length: 0
content-security-policy: frame-ancestors 'none'
date: Mon,28 Oct 2024 08:28:53 GMT
server: Kestrel
strict-transport-security: max-age=2592000; includeSubDomains
x-content-type-options: nosniff
Response code: 200
Response body: empty
This call closes the batch that was previously created and Open. This action will put the batch into Closed state and Aico background service will process the batch and create the Aico documents.
Request URL: https://localhost:7060/staging/batches/6/close
Curl: curl -X 'PATCH' \
'https://localhost:7060/staging/batches/6/close' \
-H 'accept: */*' \
-H 'Authorization: Bearer {token}'
Response headers:
cache-control: no-store
content-length: 0
content-security-policy: frame-ancestors 'none'
date: Mon,28 Oct 2024 08:32:19 GMT
server: Kestrel
strict-transport-security: max-age=2592000; includeSubDomains
x-content-type-options: nosniff
Response code: 200
Response body: empty
It is possible to create a new batch including one or more documents in a single call. This will also automatically Close the batch, and the document import will automatically start.
Request JSON body:
{
"note": "Batch created from a special source",
"externalId": "123",
"validateOnly": false,
"documents": [
{
"companyCode": "MYCOMPANY",
"documentTemplateCode": "StagingDT1",
"externalId": "1234",
"comments": "Some comments",
"text01": "My textHeader1 and textHeader2 value",
"rows": [
{
"lineNumber": 0,
"text01": "My textColumn2 value"
}
]
}
]
}
Request URL: https://localhost:7060/staging/clients/1/batches
Curl: curl -X 'POST' \
'https://localhost:7060/staging/clients/1/batches' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-d '{
"note": "Batch created from a special source",
"externalId": "123",
"validateOnly": false,
"documents": [
{
"companyCode": "MYCOMPANY",
"documentTemplateCode": "StagingDT1",
"externalId": "1234",
"comments": "Some comments",
"text01": "My textHeader1 and textHeader2 value",
"rows": [
{
"lineNumber": 0,
"text01": "My textColumn2 value"
}
]
}
]
}'
Response headers:
cache-control: no-store
content-security-policy: frame-ancestors 'none'
content-type: application/json; charset=utf-8
date: Mon,28 Oct 2024 08:20:34 GMT
server: Kestrel
strict-transport-security: max-age=2592000; includeSubDomains
x-content-type-options: nosniff
Response code: 200
Response body: 7
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article