title and destination_url are required. destination_url is what desktop visitors get, and what mobile visitors get if nothing else applies — it is the most-used path, not a fallback afterthought.
The fields
Each platform takes the same four, prefixedapple_ or android_:
*_custom_url is used when *_behaviour is custom_url or when *_no_app_behaviour is custom.
When *_no_app_behaviour is unset and neither store nor custom URL is configured, visitors without the app go to destination_url (the web destination).
Deep link to the right screen
The value of*_intent_url is the difference between a link that works and one that technically works.
https:// URL (Universal Link on iOS, App Link on Android). Installed users open only when the Dynamic Link domain is associated — Chrome self-handles an https intent://, so the browser cannot launch the app. See App association.
Dropping someone on your home screen when they clicked a link about a specific product means they have to find it again, and most will not. Point the intent URL at the actual content.
How https fallbacks work
The domain passed to create must have
link_usage of Dynamic Links. Shared shortlink domains are rejected.
Create and update accept the same password and expiration fields as shortlinks: password_protected, password, link_expiration_enabled, expires_at, and expiration_url. Password protection requires Growth or above, and link expiration requires a paid plan. Omit the fields on update to leave the stored password and expiration unchanged. Send password_protected=false or link_expiration_enabled=false to clear them. The response never includes the password hash.
When the OS delivers the short URL to the app, call GET /{back_half}?format=json so the app can read app_url and the click is recorded as app_open.
Where fallbacks go
Three cases, and all three are worth setting deliberately:Updating
Listing
Testing before you ship
Test on real devices, in all four states. Simulators do not exercise app association the way a real device does.1
iOS, app installed
OS should open the app with no Safari flash; the app calls JSON resolve.
2
iOS, app not installed
Should reach the App Store listing.
3
Android, both states
Same two checks, including from an in-app browser such as WhatsApp or Instagram.
4
Desktop
Should reach
destination_url.