TextKitDocs

Add a link domain

Add a subdomain of your own (links.example.com) to carry short links (shorten_links on POST /messages).

POST/v1/link-domains

Body Parameters

  • domainstringrequired

    Example: links.example.com.

Details

Carriers filter shared shorteners, so short links only ever go on your own domain. The response lists two DNS records to add: a CNAME to our link host and a TXT that proves the domain is yours.

Then call POST /link-domains/{id}/verify. Once both records check out, verify turns it on (active).

A bare domain, one of ours, a public shortener or a look-alike of a known brand is refused. Recorded in the audit log as link_domain.created.

Scope: links.

Responses

  • 201LinkDomain

    Added, with the DNS records to create

  • 400Error

    Not a usable domain, or 3 already

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 409Error

    Already on this account or another (invalid_state)

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring

    Example: ld_a1B2c3D4e5F6.

  • objectlink_domain
  • domainstring

    Example: links.example.com.

  • statuspending_dns, dns_verified, active

    pending_dns: add the records and verify. dns_verified: the records check out and it is being turned on. active: shorten_links uses it.

  • dns_recordsarray of object

    The records to create at your DNS host.

  • dns_records[].typeCNAME, TXT
  • dns_records[].namestring

    Example: links.example.com.

  • dns_records[].valuestring

    Example: links.jointextkit.com.

  • dns_records[].purposestring
  • created_atstring (date-time)
  • verified_atstring (date-time)

    Nullable.

  • activated_atstring (date-time)

    Nullable.

  • last_checkobject

    Nullable.

  • last_check.atstring (date-time)
  • last_check.cnameboolean
  • last_check.txtboolean

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 400

    Not a usable domain, or 3 already

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 409

    Already on this account or another (invalid_state)

  • 429

    Rate limit or quota exceeded