Metadata is a flexible feature in the Dots API that allows you to attach additional information to your API requests. This can include any relevant data specific to your application that will help you to manage and organize your operations.

​
What is Metadata?

Metadata in the Dots API is an object that you can include in the body of your request using the metadata parameter. It consists of key-value pairs where the key is a string identifier and the value is the data you want to attach.

​
How to Use Metadata

You can include a metadata object in your API request and the metadata is returned in the response to your request. The following example demonstrates a request to create a user where the metadata is used to store the user’s internal_id.

Dots team recommends you avoid storing sensitive information such as bank account numbers, card details, or personal identification numbers in metadata.
curl --request POST \
  --url https://api.dots.dev/api/v2/users \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Bob",
  "last_name": "Loblaw",
  "email": "bob@bobloblaw.com",
  "country_code": "1",
  "phone_number": "4154332334",
  "metadata": {
    "internal_id": "user_121344"
  }
}'

​
Sample Use Cases

You’re completely free to use the metadata feature in the way it best fits your business. Below are described some possible use cases for metadata.

  • Project ID: Attach a project ID to each payout to track payments associated with specific projects.
  • Expense Categories: Tag payments with expense categories for better financial reporting and analysis.
  • Service Levels: Tag payouts with service level agreements (SLAs) or priority levels for monitoring and reporting.

The following code block presents a metadata example for a hypothetical payment for a vendor related to a sale.

{
  "metadata": {
    "vendor_id": "vendor_567",
    "order_id": "order_890",
    "product_category": "Electronics",
    "sales_period": "Q2 2024"
  }
}