Metadata
Metadata lets you attach your own application-specific information to supported Dots resources. Dots stores this value with the resource and returns it in API responses and webhook payloads.
What is Metadata?
Pass metadata in the metadata request field. It can be any valid JSON value: an object, array, string, number, boolean, or null. An object is usually the most useful format because it lets you store named values.
How to Use Metadata
The following example creates a user with an internal identifier stored in metadata. Dots returns the metadata unchanged with the user.
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
Common uses for metadata include:
- 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.
For example, a vendor payment can store reconciliation details in an object:
{
"metadata": {
"vendor_id": "vendor_567",
"order_id": "order_890",
"product_category": "Electronics",
"sales_period": "Q2 2024"
}
}