Metadata and reference
Link each letter and verification to the records in your system.
Letters and verifications have two fields for your own data: reference and metadata. Neither is printed. Both come back in every response and every webhook.
The difference
reference | metadata | |
|---|---|---|
| What it is | One identifier of yours, as text. | Free key-value pairs. |
| Example | "invoice-2026-10-0042" | { "customer_id": "1842", "contract": "C-2026-118" } |
| Shown in the dashboard | Yes | No |
| Usable as a list filter | Yes, with ?reference= | No |
| Must be unique | No | Not applicable |
| Limit | 100 characters | 20 keys; keys up to 40 characters and string values up to 500 characters |
| When not sent | null | {} |
Use reference for the main identifier, the one someone on your team would search for in the dashboard, such as the invoice number. Use metadata for the rest of the context your system needs when a webhook arrives.
Example
{
"reference": "invoice-2026-10-0042",
"metadata": {
"customer_id": "1842",
"contract": "C-2026-118",
"billing_cycle": "2026-10"
}
}When the letter.posted event arrives, your system finds the invoice by reference and the customer by metadata.customer_id, without storing the letter id.
To find the letter for an invoice:
curl "https://api.cartaflow.com.br/v1/letters?reference=invoice-2026-10-0042" \
-H "Authorization: Bearer $CARTAFLOW_API_KEY"Since reference does not have to be unique, the response is a list. If you sent the same invoice twice on purpose, both letters show up.
Metadata rules
- Values are always strings. Send numbers as strings:
"1842", not1842. - Too many keys, or keys and values that are too long, get a 422 with
too_longand the field inparam, such asmetadata.customer_id. A value that is not a string getsinvalid_type. metadatadoes not accept nested objects.
Do not store sensitive data
Do not put passwords, card numbers, full identity documents or health data in reference or metadata. Use the record id from your system instead, which only means something to you.
Reference and Idempotency-Key
Idempotency-Key is something else: a header that stops the same letter from being created twice when you retry a request. It is not stored on the letter. The same identifier often works for both, such as the invoice id. See Idempotency.