Metadata

For all resources, you can pass a metadata field in the request body to attach additional information to the Deliver resource. You can also use the PATCH and/or PUT endpoints for each resource to update, add to, or remove the metadata. Any existing metadata will be present on all API and webhook responses throughout Deliver.

Metadata can be useful in many ways. For example, you could store a customer's username in metadata when creating that user as a Person. Deliver does not use metadata — it does not impact the status of any resource and adding, updating, or removing metadata will not result in a webhook event.

Metadata must be valid JSON and can contain up to 5 key-value pairs with key names up to 20 characters long and values up to 50 characters long. Do not store any sensitive or personally identifiable information (such as bank account numbers) in metadata.

Example Request to Create a Person With Metadata

curl --request POST \
     --url https://api-sandbox.orum.io/deliver/persons \
     --header 'Orum-Version: v2022-09-21' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "customer_reference_id": "7293mn67sl097da3f",
     "first_name": "Test",
     "last_name": "User",
     "metadata": {
     		"customer_id": "71np8dw5rd08an15",
        "username": "user123",
        "beta_access": true
     },
     "date_of_birth": "1990-03-01",
     "social_security_number": "123-45-6789",
     "addresses": [
          {
               "type": "home",
               "address1": "12 Test st",
               "city": "Testerton",
               "state": "NY",
               "country": "US",
               "zip5": "10001"
          }
     ]
}
'

Example Request to Update the Metadata on a Person

The below request will maintain the customer_id value, remove the username field and value, update the beta_access value, and add a new customer_number field with a value of 1098.

curl --request PATCH \
     --url https://api-sandbox.orum.io/deliver/persons/5ada8562-c616-4859-8999-8f148bdfaa10 \
     --header 'Orum-Version: v2022-09-21' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "customer_reference_id": "7293mn67sl097da3f",
     "first_name": "Test",
     "last_name": "User",
     "metadata": {
     		"customer_id": "71np8dw5rd08an15",
        "beta_access": false,
        "customer_number": 1098
     },
     "date_of_birth": "1990-03-01",
     "social_security_number": "123-45-6789",
     "addresses": [
          {
               "type": "home",
               "address1": "12 Test st",
               "city": "Testerton",
               "state": "NY",
               "country": "US",
               "zip5": "10001"
          }
     ]
}
'