API explorer
/
Metadata

Metadata

Many of our main API resources support metadata. Add metadata to your API entities to include additional information that you can consume in third-party systems. For example, to:
  • Add an account ID to a funding account entity to connect it to a record on a third-party system.
  • Add a user ID and an ISV ID to an uploaded document to maintain an audit trail of uploads to a record.

How we treat metadata

What you include in your metadata is up to you. We treat metadata as additional data that we don’t use in any way.

What we do with metadata:

  • Store it with the entity that it is attached to
  • Validate it to make sure that it is structured correctly as key-value pairs
  • Encrypt it while it is at rest until you complete a valid API request

What we don't do with metadata:

  • Consume it
  • Use it for any internal processes

How to add metadata to an entity

Add metadata to your entity as key-value pairs, within the following constraints:
  • Up to 20 unique keys
  • Up to 50 characters for each key name
  • Up to 1024 characters for each value
We accept only String values for the key value pairs.
We do not support nested JSON objects.

Best practices

Apply the following best practices when you add metadata to your entity:
  • Use unique key names.
  • Always validate your integration. If we receive badly constructed metadata, we return a 400 error.
  • Never display contents of metadata in a User Interface.
Never store any sensitive information in your metadata, for example, customer information, payment card details, or API keys.

Sample code

The following code sample shows the general layout that you should apply when you add metadata to an entity. 
{
  "parameter1": "value1",
  "parameter2": "value2",
  "parameter3": "value3",
  "object1": [
    {
      "object1_parameter1": "object1_value1",
	  "object1_object2": {
		"object1_object2_parameter1": "object1_object2_value1",
		"object1_object2_parameter2": "object1_object2_value2"	
		}
    }
  ],
  "metadata": {
     "key1": "value1",
	 "key2": "value2",
	 "key3": "value3"
  }
}
The following code sample shows metadata that tracks the user who uploaded a document and what ISV the user works for. The two key-value pairs to achieve this are:
  • mspwareUserID: "8cd4c706cce9498b9aa70471434b7e6e"
  • isvsId: "739573" 
{
  "purpose": "identity",
  "name": "passport",
  "description": "Merchants passport for identity verification",
  "mime-type": "application/pdf",
  "attachments": [
    {
      "content": "k6wdryMd3OBtib0Dd/uLh7CclOSw3UXyXmMoYW0DxR0="
	  }
  ],
  "metadata": {
      "mspwareUserId": "8cd4c706cce9498b9aa70471434b7e6e",
	  "isvsId": "739573"
  }
}