Claims BI API

1. Overview

Jakamo is a great tool for handling claims and sharing them with suppliers. Claims can be created in Jakamo UI or REST API integration. A claim item in Jakamo contains information about the actual claim but also about the supplier's response to a claim.

This article focuses on the JSON-based REST API over HTTPS for retrieving claims information to be used in external systems (BI reporting etc). Claims BI API has a GET endpoint for retrieving claims data from Jakamo. Claims BI API support for getting incremental data as a default. The possibility also to fetch all the data.

Request demo accounts from Jakamo Support Team (support@thejakamo.com) to create a Claims BI integration from your system to Jakamo.

There are two similar Jakamo environments available for you: the test (=demo) environment and the production environment.

• Test environment is for testing purposes. Start your integration testing and user training in a test environment.
• Production environment is for the live use with other Jakamo companies.

2. API authorization

Jakamo Claims BI API uses OAuth2.0 authentication. If you are still using basic authentication, we highly recommend migrating to OAuth 2.0 authorization. Find step-by-step instructions on how to move from basic authentication to use OAuth2.0.

3. Claims BI API endpoints

Jakamo environment	HTTP request	Jakamo Claims BI API endpoint
Test environment	GET	https://demo.thejakamo.com/api/claims
Production environment	GET	https://www.thejakamo.com/api/claim

3.1 Supported query parameters

Query parameter	Data type	Values	Default	Description
type	string	sent, received	received	Fetch either sent or received claims.
all	boolean	true, false	false	Fetch all claims instead of default incremental behavior.
mapCompanyIdentifiers	boolean	true, false	false	Maps companies and own business units to identifier on a mapping table for this integration. Requires mapping table to be set.

3.2 Example request

Fetch all sent claims (shared with suppliers) from the test environment:

GET https://demo.thejakamo.com/api/claims?type=sent&all=true

Fetch all sent claims (shared with suppliers) from the production environment:

GET https://www.thejakamo.com/api/claims?type=sent&all=true

4. Request response messages

The table below presents the most common API request responses from Jakamo RFQ API.

HTTP response status code	Response body	Additional information
200 OK	Claims data message	Claims data successfully retrieved from the Claims BI API.
401 Unauthorized	Empty	Authorization method is incorrect or there is a problem with authentication credentials or OAuth application.

5. Example message

The Claims BI API returns your claim data according to the endpoint query parameters. Currently, Jakamo can return all claims shared with suppliers and their data, in addition to internally shared claims. Claims shared with Master Data company are not returned.

Example message 1: Returned json message containing claim data

[
    {
        "ItemID": 32564, // Jakamo item ID which is unique number
        "OwnerCompany": "Customer Company AB", 
        "SharedWith": "Supplier AB", // This is the supplier the claims is shared with (their Jakamo account's name)
        "Title": "This is a title of the claim", 
        "Status": "Waiting for response", // Current status of the claim in Jakamo
        "CreatedAt": "2024-03-20 08:38:43.269043", // Date and time claim is created to Jakamo in UTC0
        "EditedAt": "2024-03-20 08:38:43.269043",
        "AuthorUser": "Joe Doe",
        "PurchaseOrderNumber": "PO12345",
        "OrderConfirmationNumber": "Confirmation 12345",
        "ProjectReference": "PR12345",
        "ProductNumber": "PN12345",
        "ClaimID": "JA000011", // Claim ID either provided by customer or autogenerated by Jakamo
        "CostEffectsCurrency": "EUR",
        "DefectTime": "2018-01-01 00:00:00", // Date and time when the defect is occurred
        "DefectType": "Work defect",
        "DefectClassification": "Minor deviation",
        "ClaimDescription": "This is the description of the defect.", // You description of the claim and defect
        "ClaimedCosts": "1200",
        "TotalCosts": "1200",
        "OtherCompensation": "Repair of the surface.",
        "ClaimedItems": 12,
        "ClaimedItemsUnit": "PCS",
        "InspectionHours": "130",
        "LossHours": "330",
        "ProcessPhase": "Assembly", // Part of supplier's response
        "AgreedCompensation": 1200, // Part of supplier's response
        "AgreedCompensationCurrency": null, // Part of supplier's response
        "Containment": "This is containment information supplier can provide.", // Part of supplier's response
        "CauseAnalysis": "This is cause analysis done by supplier.", // Part of supplier's response
        "CorrectiveActions": "This is section for corrective actions provided by supplier.", // Part of supplier's response
        "PrecautionaryActions": "This is precautionary actions provided by supplier.", // Part of supplier's response
        "FollowUpActions": "This is proposed follow-up actions provided by supplier.", // Part of supplier's response
        "FollowUpTime": "2025-05-28 00:00:00", // Part of supplier's response
        "VendorReference": "REF 299992", // Part of supplier's response
        "VendorMaterialID": "773773", // Part of supplier's response
        "Tags": "tag1,tag2", // Possible tags added to claim item in Jakamo
        "WaitingForResponseElapsedTimeHours": "453.7",
        "InProgressElapsedTimeHours": "45.1",
        "CompletedElapsedTimeHours": "3.9",
        "TotalElapsedTimeHours": "502.7",
        "TotalElapsedTimeDays": "20.95",
        "Accepted": true,
        "FollowUpDone": false,
        "Cancelled": false
    }
]

If you enable the query parameter mapCompanyIdentifiers, the returned claim data will include identifier fields for both:

• the supplier number you have defined for the partner the claim is shared with, and
• the internal identifier (company number or business unit number) defined for your own company

This feature requires that a mapping table has been configured for your integration.

Example message 2: Partner and own identifiers returned in the claim data message

"SharedWithCompanyIdentifier": {
            "identifier": "12345",
            "identifierType": "MAPPING_TABLE",
            "identifierSourceName": "Claims BI integration mappings"
        },
"OwnerCompanyIdentifier": {
            "identifier": "65432",
            "identifierType": "MAPPING_TABLE",
            "identifierSourceName": "Claims BI integration mappings"
        }

6. Handling incoming message queue

See the general Jakamo API queue handling instructions from incoming message queue handling page. Jakamo stores all outgoing messages in an API queue. By making an HTTP GET request to the response endpoint Jakamo delivers the first message from the queue.

Messages in the response queue must be cleared after they have been processed. The response message contains an x-acknowledge-uri header. Posting to this URI removes that message from the queue. After that, the next message from the queue will be returned.

7. Steps to go to production

Contact Jakamo Support Team (support@thejakamo.com) to enable the Claims BI API in Jakamo. Once the integration is activated to your production account by Jakamo staff, you can define API authentication method on the Integrations page found from Jakamo's upper-left hidden menu. After that, you can retrieve claims data from your Jakamo company account.

Help & Support

Didn't you find what you were looking for? Send an email to Jakamo support (support@thejakamo.com) and we will help you.