# Link domains

Source: https://parasend.com/docs/api/link-domains

## Endpoints

- [List link domains](https://parasend.com/docs/api/link-domains/list.md): `GET /v1/recipient_domains`
- [Retrieve a link domain](https://parasend.com/docs/api/link-domains/retrieve.md): `GET /v1/recipient_domains/{id}`
- [Check a link domain](https://parasend.com/docs/api/link-domains/check.md): `POST /v1/recipient_domains/{id}/check`

## The RecipientDomain object

- `id` (string, required): The link domain's ID, starting `cdm_`.
- `object` (string, required): Always `recipient_domain`.
- `hostname` (string, required): The hostname your delivery links use, such as `afhending.fyrirtaeki.example`: lower case, an internationalised name in its ASCII (`xn--`) form. At least three labels, so not a bare domain, and never under parasend.com.
- `state` (string, required): `pending_dns`: the ownership TXT or the CNAME is not seen yet. `verifying`: both are seen and the domain is being set up. `issuing_cert`: its certificate is being issued. `active`: links use it. `degraded`: it was active and a check now fails. `failed`: it could not be set up, or stayed degraded for 72 hours. `removed`: taken off your list. One of: `pending_dns`, `verifying`, `issuing_cert`, `active`, `degraded`, `failed`, `removed`.
- `reason` (string · nullable, required): Why it waits, is degraded or failed: ownership_not_found, cname_not_found, lookup_failed, tenants_off, certificate_pending, deploying, dns_not_pointing, claimed_elsewhere, hostname_in_use_elsewhere (the hostname is still on another CloudFront distribution: remove it there, then Check now), certificate_<status>, tenant_missing, tenant_disabled, degraded_72h, organization_erased.
- `records` (array of object, required): The ownership TXT and the CNAME, expected and seen; a caa record only when CAA is published.
  - `records[].record` (string, required): Which record this is: `ownership`, the TXT record that proves the hostname is yours; `cname`, the CNAME that points it at Parasend; `caa`, your CAA record, listed only when you publish one. One of: `ownership`, `cname`, `caa`.
  - `records[].type` (string, required): The DNS record type: `TXT` for `ownership`, `CNAME` for `cname`, `CAA` for `caa`. One of: `TXT`, `CNAME`, `CAA`.
  - `records[].name` (string, required): The DNS name to publish at (for caa, the name whose CAA governs the hostname).
  - `records[].value` (string, required): What it should hold.
  - `records[].seen` (array of string, required): What the last check found there.
  - `records[].ok` (boolean, required): Whether the last check found the record as it should be.
  - `records[].via` (string, optional): Ownership proved by the parent domain, which your organisation alone has verified for e-mail. One of: `parent_domain`.
- `caa_hint` (boolean, required): CAA is published and names no Amazon issuer, so no certificate can be issued.
- `certificate` (object · nullable, required): The hostname's TLS certificate, by its `status`; null until one has been requested.
  - `certificate.status` (string, optional): pending-validation, issued, failed, validation-timed-out, revoked, expired or inactive.
- `used_by` (object, required): How many brand profiles in use name this domain in their current version (`brand_profiles`).
  - `used_by.brand_profiles` (integer, required): Profiles in use whose current version names it (a count).
- `verified_at` (string · date-time · nullable, required): When both DNS records were first seen together; the hostname is your organisation's from then on.
- `active_since` (string · date-time · nullable, required): When the domain last became `active`, in ISO 8601 (UTC); null if it never has.
- `degraded_since` (string · date-time · nullable, required): When the domain, while active, began failing its checks, in ISO 8601 (UTC); null when it is not degraded. After 72 hours degraded it becomes `failed`.
- `failed_at` (string · date-time · nullable, required): When the domain became `failed`, in ISO 8601 (UTC); null otherwise.
- `last_checked_at` (string · date-time · nullable, required): When its DNS was last checked, in ISO 8601 (UTC); null before the first check. Parasend checks every 15 minutes, and when you call `POST /recipient_domains/{id}/check`.
- `created_at` (string · date-time, required): When the domain was added, in ISO 8601 (UTC).
- `removed_at` (string · date-time · nullable, required): When the domain was removed with `DELETE /recipient_domains/{id}`, in ISO 8601 (UTC); null while it is on your list.