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.
`smartLink`	string	Response only	The full short URL (e.g. `https://re.codelloy.com/spring-sale`). Reflects your active custom domain when one is set.
`isActive`	boolean	Request + Response	Defaults to `true`. `false` archives the link (HTTP 410 `EN002` at click time).
`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 — `title`, `description`, `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	Java `LocalDateTime` (e.g. `"2026-05-15T10:30:00.742912"`) — no `Z` suffix, microsecond precision, no timezone. Always interpret as UTC. Parse with a `LocalDateTime` / naive-datetime strategy on the client.
`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 Manage Apps dashboard (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 Manage 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.