Skip to main content
Each hit returned by Clinia is enriched with metadata information such as createdAt and updatedAt, which are generated automatically by Clinia’s infrastructure. To allow for more flexibility and support a system migration, Clinia’s Resource API, Relationship API, Object API, Bulk API and Bundle API allow specifying metadata information in a create or upsert operation (but not update). System modifiable metadata properties are: 
{
    "createdAt": "<datetime>",
    "updatedAt": "<datetime>",
    "identifier": [
        {
            // Identifier type
        }
    ]
}

​
Metadata Rules

Some validation rules are imposed on those metadata to ensure consistency with system-generated values. Those are:
  • If a value is specified for updatedAt, one must also be provided for createdAt
  • The datetime value of the updatedAt must be greater or equal to the createdAt
  • The createdAt and updatedAt datetime values cannot be in the future.
  • The identifier field must contain Identifier Type with distinct combined values of system, use and value fields.
    • Field use can’t take the reserved value "source"
    • Field system can’t take the reserved value "mdm"

​
Examples

This setup creates a demo registry source with minimal profiles and a relationship so the examples can run consistently.
1

Create a source

curl -X PUT "https://$CLINIA_WORKSPACE/catalog/v1/sources/history-demo" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "registry"
}'
2

Create minimal profiles

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/profiles/patient" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "ROOT",
  "properties": {
    "name": {
      "type": "array",
      "items": {
        "type": "humanname"
      }
    },
    "birthDate": {
      "type": "date"
    }
  }
}'

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/profiles/practitioner" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "ROOT",
  "properties": {
    "name": {
      "type": "array",
      "items": {
        "type": "humanname"
      }
    }
  }
}'
3

Create a relationship definition

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/relationship-definitions/treats" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "from": {
    "profileKey": "practitioner",
    "includeKey": "practitioner",
    "includeCardinality": "0:*"
  },
  "to": {
    "profileKey": "patient",
    "includeKey": "patient",
    "includeCardinality": "0:*"
  },
  "description": "A relationship indicating that a practitioner treats a patient",
  "properties": {}
}'
4

Create an object collection

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/collections/documents" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "objects",
  "objectDefinition": {
    "properties": {
      "document": {
        "type": "object",
        "properties": {
          "title": {
            "type": "symbol"
          }
        }
      }
    }
  }
}'

​
Resource Upsert

Specify system-modifiable metadata when creating or replacing a resource. See the Resource API Reference. 
curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": [
      {
        "given": [
          "John"
        ],
        "family": "Doe"
      }
    ],
    "birthDate": "1980-01-01"
  },
  "meta": {
    "createdAt": "2020-05-01T10:00:00Z",
    "updatedAt": "2021-06-15T12:30:00Z",
    "identifier": [
      {
        "system": "https://hospital.example/mrn",
        "value": "12345",
        "use": "external"
      }
    ]
  }
}'
Before fetching the resource, make sure the ingestion task is completed. 
curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "patient-001",
  "type": "patient",
  "includes": {},
  "meta": {
    "createdAt": "2020-05-01T10:00:00Z",
    "updatedAt": "2021-06-15T12:30:00Z",
    "identifier": [
      {
        "system": "https://hospital.example/mrn",
        "value": "12345",
        "use": "external"
      }
    ],
    "source": "history-demo"
  },
  "data": {
    "name": [{ "given": ["John"], "family": "Doe" }],
    "birthDate": "1980-01-01"
  }
}

​
Relationship Create

Create a relationship with historical metadata on the link itself. See the Relationship API Reference. First, ensure the related resources exist (no global seeding required): 
curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": [
      {
        "given": [
          "John"
        ],
        "family": "Doe"
      }
    ],
    "birthDate": "1980-01-01"
  }
}'

curl -X PUT "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/practitioner/pract-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": [
      {
        "given": [
          "Alice"
        ],
        "family": "Anderson"
      }
    ]
  }
}'

curl -X POST "https://$CLINIA_WORKSPACE/sources/history-demo/v1/relationships/treats" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "from": {
    "type": "practitioner",
    "id": "pract-001"
  },
  "to": {
    "type": "patient",
    "id": "patient-001"
  },
  "meta": {
    "createdAt": "2021-07-01T09:00:00Z",
    "updatedAt": "2021-07-01T09:00:00Z",
    "identifier": [
      {
        "system": "https://ehr.example/relationship-id",
        "value": "rel-7890",
        "use": "external"
      }
    ]
  }
}'
Before fetching the relationship, make sure the ingestion task is completed. 
curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/relationships/treats/pract-001.patient-001" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "pract-001.patient-001",
  "type": "treats",
  "from": { "type": "practitioner", "id": "pract-001" },
  "to": { "type": "patient", "id": "patient-001" },
  "data": null,
  "meta": {
    "createdAt": "2021-07-01T09:00:00Z",
    "updatedAt": "2021-07-01T09:00:00Z",
    "identifier": [
      {
        "system": "https://ehr.example/relationship-id",
        "value": "rel-7890",
        "use": "external"
      }
    ],
    "source": "history-demo"
  }
}

​
Object Create

Historical metadata can also be attached to file-based objects. Include the meta block inside the JSON payload of the multipart data field when calling Create an object. 
curl -X POST "https://$CLINIA_WORKSPACE/sources/history-demo/v1/objects/documents" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -F 'data={"id":"@rootId","meta":{"createdAt":"2019-04-30T14:15:00Z","updatedAt":"2020-02-01T09:00:00Z"},"data":{"document":{"title":"Historical consent"}}}' \
  -F "file=@~/documents/consent.pdf;type=application/pdf"
After the ingestion task completes, retrieve the object with Get an object from the registry to confirm the provided timestamps are stored in meta.createdAt and meta.updatedAt.

​
Bulk Request

Process multiple resource creations with historical metadata using the bulk resources endpoint, then poll the task result. Also see the Task API Reference. 
curl -X POST "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operations": [
    {
      "action": "CREATE",
      "create": {
        "type": "patient",
        "id": "patient-002",
        "data": {
          "name": [
            {
              "given": [
                "Carla"
              ],
              "family": "Nguyen"
            }
          ],
          "birthDate": "1990-02-02"
        },
        "meta": {
          "createdAt": "2019-03-10T08:00:00Z",
          "updatedAt": "2019-03-10T08:00:00Z",
          "identifier": [
            {
              "system": "https://hospital.example/mrn",
              "value": "67890",
              "use": "external"
            }
          ]
        }
      }
    }
  ]
}'
Before fetching the resource, make sure the ingestion task is completed. 
curl -X GET "https://$CLINIA_WORKSPACE/sources/history-demo/v1/resources/patient/patient-002" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "patient-002",
  "type": "patient",
  "includes": {},
  "meta": {
    "createdAt": "2019-03-10T08:00:00Z",
    "updatedAt": "2019-03-10T08:00:00Z",
    "identifier": [
      {
        "system": "https://hospital.example/mrn",
        "value": "67890",
        "use": "external"
      }
    ],
    "source": "history-demo"
  },
  "data": {
    "name": [{ "given": ["Carla"], "family": "Nguyen" }],
    "birthDate": "1990-02-02"
  }
}
⌘I