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 or basic authentication as an authentication method. OAuth2.0 is the preferred method. Find step-by-step instructions on how to move from basic authentication to use OAuth2.0.
For basic authentication, the username and password for the API are set inside the Jakamo account in the Integrations settings with the CHANGE CREDENTIALS functionality. If you have multiple integrations enabled towards your Jakamo company account, please use different credentials for each integration.
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 |
Supported query parameters:
- (string) type: sent|received
- default: received
- fetch either sent or received claims
- (boolean) all: true|false
- default: false
- fetch all claims instead of default incremental behavior
An example request on fetching all sent claims (shared with suppliers) from test environment:
HTTP GET https://demo.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 authenticaion credentials |
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, but cannot return any information about claims shared internally.
Example: 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
}
]
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.
Didn't you find what you were looking for? Send an email to Jakamo support (support@thejakamo.com) and we will help you.