For all resources, you can pass a metadata field in the request body to attach additional information to the Momentum 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 Momentum.

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 in Momentum. Metadata is not used by Momentum -- 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 (ex: bank account numbers) in metadata.

Sample request to create a person with metadata

curl --request POST \
     --url https://api-sandbox.orum.io/momentum/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"
          }
     ]
}
'

Sample 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/momentum/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"
          }
     ]
}
'