GuidesReferenceChangelogAPI Upgrades

Metadata

Storing auxiliary information in Check's resources

Suggest Edits

Many of Check’s resources expose a metadata parameter to allow users to store additional loosely structured information within our system. metadata is structured as a series of key-value pairs, where all keys and all values must be strings. There is a maximum capacity of 50 keys per resource, with key names limited to 40 characters and values limited to 500 characters.

The following resources support the metadata parameter:

When to use metadata

Storing additional fields

metadata can be used to supplement storage needs which are not met by the existing fields exposed by a particular resource. An example use case is to store auxiliary fields not included in the schema for Employee, such as job_title or time_zone, in metadata. With metadata, job_title, time_zone and any additional fields required by the consumer’s system, are co-located on the Employee object.

Linking objects with IDs

The ability to store extra information on objects also allows a user to link their system’s representation of a record to a corresponding record in Check. By storing a unique reference ID from your system in the metadata field, records in our system can be easily correlated to your system’s representation.

Annotating items with a note

Use metadata to add a descriptive annotation to any of the supported resources. For example, you can attach a note to a PayrollItem that describes any changes or corrections made.

How to use metadata

metadata can be set both during the creation of an object and when updating an object.

The following example creates a Company object with metadata that contains a UUID mapped to an internal_id key.

curl --request POST \
  --url https://sandbox.checkhq.com/companies \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
          "address": {
            "country": "US",
            "line1": "1077 E Arques Ave",
            "city": "Sunnyvale",
            "state": "CA",
            "postal_code": "94085"
          },
          "legal_name": "Capsule Corp",
          "phone": "4085550164",
          "metadata": {
            "internal_id": "1287703c-e1ef-45bc-9ebc-06ec7009629f"
          }
		}'

Example response

{
   "id": "com_7L6EbR0RxgLxuvZybVBG",
    ...
   "metadata": {
       "internal_id": "1287703c-e1ef-45bc-9ebc-06ec7009629f"
   }
}

We can easily update the internal_id of this metadata object with a PATCH request that includes that key with a new value.

Note: Be sure to include the id of the resource being updated as a path parameter. In this example, we are using the id of the Company created above.

curl --request PATCH \
  --url https://sandbox.checkhq.com/companies/com_7L6EbR0RxgLxuvZybVBG \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
          "metadata": {                                          
            "internal_id": "36e7d947-63e8-48bb-80ab-735769078294"
          }    
		}'

Example response

{
   "id": "com_7L6EbR0RxgLxuvZybVBG",
    ...
   "metadata": {
       "internal_id": "36e7d947-63e8-48bb-80ab-735769078294"
   }
}

Similarly, additional keys can be added to metadata using a PATCH request.

curl --request PATCH \
  --url https://sandbox.checkhq.com/companies/com_7L6EbR0RxgLxuvZybVBG \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
          "metadata": {                                          
            "foo": "bar"
          }    
		}'

As shown in the example response below, the new key foo and its corresponding value are merged into the existing metadata.

Example response

{
   "id": "com_7L6EbR0RxgLxuvZybVBG",
    ....
   "metadata": {
       "internal_id": "36e7d947-63e8-48bb-80ab-735769078294",
       "foo": "bar"
   }
}

To delete a single key within metadata, simply pass in the key-value pair with the value set to null in your PATCH request.

curl --request PATCH \
  --url https://sandbox.checkhq.com/companies/com_7L6EbR0RxgLxuvZybVBG \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
          "metadata": {                                          
            "foo": null
          }    
		}'

By passing null as the value for foo, we delete it from the metadata object, as shown in the example response below.

Example response

{
   "id": "com_7L6EbR0RxgLxuvZybVBG",
    ...
   "metadata": {
       "internal_id": "36e7d947-63e8-48bb-80ab-735769078294",
   }
}

To delete all existing metadata, pass an empty object as the value ({}) for metadata in the PATCH request.

curl --request PATCH \
  --url https://sandbox.checkhq.com/companies/com_7L6EbR0RxgLxuvZybVBG \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
          "metadata": {}    
		}'

Example response

{
   "id": "com_7L6EbR0RxgLxuvZybVBG",
    ...
   "metadata": {}
}

Updated over 2 years ago