Base URL and versioning
All endpoints use the v1 prefix:
https://api.heydollr.app/v1/<resource>
- Content-Type:
application/json for requests and responses
- Timestamps: ISO 8601 (e.g.
2025-06-01T14:30:00Z)
- Currency: ISO 4217, uppercase (e.g.
USD, LRD)
- Phone: E.164 digits without
+ (e.g. 231771234567)
- Amounts: Positive numbers; minimum
0.01 for decimals, 1 for integers
reference_id: Version-4 UUID on every execution (idempotency key)
Resource ID types
Some fields accept the same logical ID in different JSON types depending on the endpoint:
| Field | Endpoint | JSON type | Example |
|---|
session_id | POST /v1/executions/* | string | "55" |
session_id | POST /v1/realtime-keys/collection | integer | 55 |
payment_account_id | Executions | string | "18" |
payout_account_id | Sessions / executions | integer or number | 18 |
source_id | Sessions, status, predictions | integer | 101 |
source_kind vs source_type
A frequent source of 422 errors:
| Context | Field name | Used on |
|---|
| Creating checkout source | source_kind | POST /v1/checkouts/create |
| Sessions, status, links, predictions | source_type | POST /v1/sessions/checkout, GET /v1/status/source, etc. |
INVOICE or ORDER.
// Checkouts create
{ "source_kind": "INVOICE" }
// Checkout session
{ "source_type": "INVOICE", "source_id": 101 }
SUBSCRIPTION appears in some OpenAPI enums but is not publicly supported yet.
Validation errors (422)
{
"detail": [
{
"loc": ["body", "currency"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
detail array for field-level messages.
HTTP status codes
| Code | Meaning | Typical action |
|---|
200 | Success | Use response body |
401 | Unauthorized | Refresh JWT |
403 | Forbidden | Check verification / permissions |
404 | Not found | Verify resource ID |
422 | Validation error | Fix payload per detail |
429 | Rate limited | Back off; honor Retry-After |
5xx | Server error | Retry with exponential backoff |
Last modified on June 23, 2026
