Example use of the Cost Codes API¶

The following section aims to give a brief example use case for loading cost codes. The section does not go into an elaborate scenario, as loading cost codes is very straightforward.

Scenario: loading cost codes from a Finance file¶

Currently, the integration supports pushing cost codes into Sapio LIMS. Therefore, this scenario is for the Integration Hub to load a batch of cost codes, received from ERP/Finance as a file, into Sapio.

Assume that Finance has issued a file containing a new cost code S-12345 for a science project studying leukaemia in children with Down syndrome. The cost code needs to exist in Sapio before any spend can be assigned to it. The details from the file are as follows:

1
2
3
4
5
6
7
8

{
  "ID": "S-12345",
  "Type": "Science Project",
  "Description": "Leukaemia in Children with Down Syndrome",
  "Status": "Active",
  "StartDate": "2026-06-01T00:00:00Z",
  "EndDate": "2026-12-31T23:59:59Z"
}

To achieve this, the Integration Hub would need to:

1. Authenticate with the Cost Codes API.
2. Prepare and send the payload to the POST /cost_codes/v1 endpoint of the integration.

Authenticating with the API¶

In order to authenticate, the caller would have to follow the standard OAuth 2.0 protocol, as explained in the "Authentication & Authorisation Strategy" section. Basically, the calling application would need to invoke a /token endpoint and receive a token, and use the token in the headers to authorise with the POST /cost_codes/v1 endpoint. To receive the token, the client would have to use the client credentials established as part of the onboarding process discussed in the "How to use" section.

Preparing the payload¶

In order to prepare the payload, the Integration Hub would need to determine:

1. Which cost codes from the file are to be loaded
2. Whether any of them already exist in Sapio

These two points are dependent on each other. Sapio enforces uniqueness on the project code, and the load is atomic — so if even one code in the batch already exists, the whole batch is rejected and nothing is created.

Also, every entry must carry a valid project code and description; if either is missing or malformed, the integration would respond with a "Bad Request" 400.

After the Integration Hub has the aforementioned two points figured out, they can prepare the payload as follows — a JSON array, with one entry per cost code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

[
  {
    "Body": {
      "Project": {
        "ProjectIdentifier": {
          "ID": "S-12345",
          "Type": "Science Project"
        },
        "Description": "Leukaemia in Children with Down Syndrome",
        "Lifecycle": {
          "Status": "Active",
          "EffectivePeriod": {
            "StartDate": "2026-06-01T00:00:00Z",
            "EndDate": "2026-12-31T23:59:59Z"
          }
        }
      }
    }
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

curl --location 'https://ppd.integration-hub.sanger.ac.uk/cost_codes/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ***' \
--data '[
  {
    "Body": {
      "Project": {
        "ProjectIdentifier": {
          "ID": "S-12345",
          "Type": "Science Project"
        },
        "Description": "Leukaemia in Children with Down Syndrome",
        "Lifecycle": {
          "Status": "Active",
          "EffectivePeriod": {
            "StartDate": "2026-06-01T00:00:00Z",
            "EndDate": "2026-12-31T23:59:59Z"
          }
        }
      }
    }
  }
]'

After the request has been submitted, the integration would return a 201 Created, with one entry per submitted cost code containing the project ID and the record ID that Sapio generated:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[
  {
    "Project": {
      "ProjectIdentifier": {
        "ID": "S-12345",
        "RecordID": "70157"
      }
    }
  }
]