How the Core Data API works

This documentation outlines a structured approach for importing core data into Candis using the Candis API. It provides guidance on:

Creating new or updating existing Core Data entries in Candis.
Fetching the import status after submission.

For more information on supported core data types, refer to the Candis Core Data API documentation.

Creating Core Data Entries in Candis

To create core data entries in Candis, you must submit a request to create an import job using the following endpoint:

Endpoint:
POST https://api.candis.io/v1/organizations/{organizationId}/imports/{core-data-type}

Sample Request (General Ledger Account)

curl --request POST \
     --url https://api.candis.io/v1/organizations/{organizationId}/imports/general-ledger-accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "accountCode": "GLA-000",
    "name": "General Ledger Account"
  }
]
'

Sample Response

{
  "processId": "9924bb4a-7ee9-4b6a-ac7b-30fdbe6b0031"
}

The processId returned in the response is critical for tracking the status of the import. The import process is asynchronous, meaning the time required to complete the task depends on the request's size. You can use the processId to fetch the status of the import using the Import Logs endpoint.

Updating Core Data Entries in Candis

To update existing core data entries, use the following endpoint to submit an import update request:

Endpoint:
PUT https://api.candis.io/v1/organizations/{organizationId}/imports/{core-data-type}

Sample Request (General Ledger Account)

curl --request PUT \
     --url https://api.candis.io/v1/organizations/{organizationId}/imports/general-ledger-accounts \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "accountCode": "GLA-000",
    "name": "General Ledger Account 1"
  }
]
'

Sample Response

{
  "processId": "9924bb4a-7ee9-4b6a-ac7b-30fdbe6b0031"
}

Fetch Import logs

To retrieve the status of an import process, identified by the processId, use the following endpoint. The response provides details about the status, errors (if any), and timestamps.

Endpoint:
GET https://api.candis.io/v1/organizations/{organizationId}/imports/{processId}

Sample Request

curl --request GET \
     --url 'https://api.candis.io/v1/organizations/organizationId/imports/9924bb4a-7ee9-4b6a-ac7b-30fdbe6b0031?offset=0&limit=50' \
     --header 'accept: application/json'

Sample Response

{
  "jobStatus": "PROCESSED",
  "events": [
    {
      "id": "GLA-000",
      "processId": "9924bb4a-7ee9-4b6a-ac7b-30fdbe6b0031",
      "organizationId": "alpha-organization",
      "status": "FAILED",
      "importErrors": [
        "BOOKING_ACCOUNT_ALREADY_EXISTS"
      ],
      "operation": "CREATE",
      "createdAt": "2024-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "pageCount": 1,
    "pageSize": 1,
    "totalCount": 1
  }
}