Field Reference

Complete reference for the data objects returned by the Codelloy External API. Fields marked Response only (server-controlled) are computed by the backend and cannot be set or overridden by the caller (any value supplied in the request body is silently ignored or overwritten).

Short URL Object

The primary object returned by POST /shortenedUrl/save, POST /shortenedUrl/bulkSave, and the list endpoint.

Field	Type	Direction	Description
`url`	string	Request + Response	Destination URL. Required on create.
`shortCode`	string	Request + Response	Unique alias for the short link. 7-50 characters, alphanumeric / hyphen / underscore only (regex `^[a-zA-Z0-9_-]{7,50}$`). Auto-generated when omitted on create; required on update.
`shortLinkName`	string	Request + Response	Human-readable label shown in the dashboard list view. Optional but strongly recommended for API-created links.
`customDomain`	string	Request only	Optional. One of your org’s active custom domains to serve this link on; omit to use your org’s primary domain. A value that isn’t an active domain of your org is rejected with `400` (`VE001`).
`smartLink`	string	Response only	The full short URL (e.g. `https://go.yourbrand.com/spring-sale`). Reflects the chosen `customDomain`, or your org’s primary domain, or `re.codelloy.com` when no custom domain applies.
`isActive`	boolean	Request + Response	Defaults to `true`. `false` archives the link (HTTP 410 `EN002` at click time).
`cloakEnabled`	boolean	Request + Response	`false` on create; on an update, omitting it leaves the stored value alone, so send `false` explicitly to un-cloak a link. When `true`, the destination is rendered inside a full-viewport frame instead of being navigated to, so your short-link host stays in the visitor’s address bar. Accepted on any link. Branding, not concealment — the destination stays visible in the page source, the network tab, and link previews. A destination sending `X-Frame-Options` or a CSP `frame-ancestors` directive that excludes your short-link host will not render in the frame, and the API reports success either way because the refusal happens in the visitor’s browser long after the write. Returned on every link read, including links created before cloaking existed — those read back as `false`. Filterable on the list endpoint via the query DSL: `query=cloakEnabled=true`.
`utmSource`	string	Request + Response	UTM source tag appended at click time.
`utmCampaign`	string	Request + Response	UTM campaign tag.
`utmMedium`	string	Request + Response	UTM medium tag.
`enableCustomMetadata`	boolean	Request + Response	When `true`, the `customMetadata` fields override the destination URL’s Open Graph preview. Requires the Metadata Preview* feature on your plan.
`customMetadataTitle`	string	Request + Response	Override title for link previews.
`customMetadataDescription`	string	Request + Response	Override description for link previews.
`customMetadataImageUrl`	string	Request + Response	Override image URL for link previews.
`effectivePreviewMetadata`	object<string, string>	Response only	Resolved preview metadata after applying overrides: the `title`, `description`, and `imageUrl` keys. Reflects what social-sharing surfaces actually see.
`deepLinks`	array	Request + Response	Array of `DeepLink` objects (see below). Omit or pass `[]` for a plain redirect-only short URL.
`createdAt`	string	Response only	ISO-8601 instant in UTC with a trailing `Z` (e.g. `"2026-05-15T10:30:00.742912Z"`), microsecond precision where the value has it. Parse with an instant or offset-aware parser (JavaScript `Date`, Python `datetime.fromisoformat` on 3.11+, Java `Instant.parse`).
`updatedAt`	string	Response only	Same shape as `createdAt`, for the most recent write.
`createdBy`	string	Response only	Either an email (dashboard-created) or `api-key:<label>` (External API-created). See audit attribution.
`updatedBy`	string	Response only	Same shape as `createdBy`, for the most recent write.
`createdVia`	enum	Response only (server-controlled)	`INTERNAL` (dashboard-created) or `EXTERNAL` (API-created). Values supplied in the request body are silently stripped on save. Filterable on the list endpoint via the query DSL: `query=createdVia=EXTERNAL`.
`lastModifiedVia`	enum	Response only (server-controlled)	Same shape as `createdVia`, for the most recent write. A row created via the dashboard and later updated via the API has `createdVia=INTERNAL, lastModifiedVia=EXTERNAL`. Filterable via the same DSL field.

Note: Fields with no value (null) are omitted from the JSON response.

DeepLink Object

One entry in the Short URL Object’s deepLinks[] array. Each entry binds a registered Mobile App to a per-platform deep-link configuration.

Field	Type	Direction	Description
`mobileAppId`	string	Required on request	12-character base64-style ID from your Mobile apps page (charset includes `[A-Za-z0-9+/]`, e.g. `"TgdAhWK+24tg"`). Treat as opaque: don’t URL-encode or split. Null / blank / unknown values return `DL001`.
`deeplinkUrl`	string	Request + Response	Custom-scheme URI to open the app (e.g. `myapp://product/123`).
`fallbackUrl`	string	Request + Response	Web URL used when `fallbackEnabled=true` and the app is not installed.
`linkBehaviour`	string	Request + Response	`"app"` (try deep link first) or `"webBrowser"` (skip the app, go straight to `url`).
`fallbackEnabled`	boolean	Request + Response	When `true`, prefer `fallbackUrl` over the Store URL on app-not-installed.
`platform`	string	Response only (server-controlled)	Reflects the registered `MobileApp.platform` enum (`"IOS"` / `"ANDROID"` / `"WEB"`). Values supplied in request bodies are silently overwritten on save.
`storeUrl`	string	Response only (server-controlled)	Reflects the current `MobileApp.storeUrl` from your Mobile apps registration. Edits are picked up immediately on the next read. Values supplied in the request body are silently overwritten on save.

Pagination Object

Returned by the list endpoint. The envelope is {response: {data: [...], page: {...}}}.

Field	Type	Description
`data`	array	Array of Short URL Objects for the current page.
`page.size`	integer	Number of records per page (matches the `size` request param).
`page.number`	integer	Current page number (zero-based).
`page.totalElements`	integer	Total number of records matching the query.
`page.totalPages`	integer	Total number of pages available.

Response Envelope

Every Codelloy API response is wrapped in the CodelloyResponse envelope:

Field	Type	Description
`response`	object	The result payload on success. Omitted on failure.
`errors`	array	A non-empty array of `Error` objects on failure. Omitted on success.

Error Object

Field	Type	Description
`code`	string	Machine-readable error code (e.g. `VE001`, `DL001`, `SML005`). See API Errors for the full catalogue.
`message`	string	Human-readable description. May contain field paths for validation failures.
`details`	object<string, any>	Optional structured payload, present on quota errors, deep-link validation, rate-limit responses, etc. Field shape varies by `code`; see API Errors.