Link Integration

Overview

Link Integration means creating a reusable capture link in the Petify Console and distributing it to your users. You can start without any server development, and a single link can serve many users.

The Console's Integration menu provides link issuance and management (the Links tab) together with API credential management (the API & SDK tab).

Creating a link

Create links in the Console under Integration → Links → Create link.

• To operate with a different target species, create a new link.
• An Identify link searches for candidates only among pets registered under the same species as its target species.
• The Identify (IDENTIFY) function can only be selected when your plan includes identification.
• For Redirect URL format rules (HTTPS, reserved parameters, and so on), see Redirect URLs & Result Delivery.

A created link gets a URL of the following form:

https://capture.petify.petnow.io/l/hl_2Xy7Qa9Kd3Lm4Np5Rs6Tu

Delivering the link URL

Passing the pet identifier (externalPetId)

Register and Verify links need to know which pet the capture is for, so append your own system's pet ID as the externalPetId query parameter when delivering the link:

https://capture.petify.petnow.io/l/hl_2Xy7Qa9Kd3Lm4Np5Rs6Tu?externalPetId=YOUR-PET-ID-123

When entry is blocked

In the following cases the capture page does not open and the user sees a notice screen instead:

• A Register or Verify link is opened without an externalPetId
• Register: the externalPetId is already registered
• Verify: the externalPetId has no registration

Link states

• Links have no expiry date or scheduled shutdown — they stay usable until deactivated, deleted, or their cap is reached.
• Activating/deactivating takes effect immediately from the link detail view.
• Deactivation and deletion block not only new capture entries but also submissions not yet accepted. A session whose final submission was already accepted is processed to completion even if the link state changes afterwards.

Managing links

• Editing: the name, Redirect URL, and registration cap can be edited. The function and target species cannot be changed.
• Cap lower bound: the cap cannot be set below the current cumulative registration count. The count is lifetime-cumulative for the link and does not decrease when registered pets are deleted.
• Deletion: deletion is permanent and unrecoverable, and the link address is never reused. Pets registered through the link are kept.
• Count limit: an account can hold at most 500 links (excluding deleted ones).

Reading results

When capture finishes, the user's browser navigates to the link's Redirect URL with petify_status (and conditionally petify_code) added as query parameters. See Redirect URLs & Result Delivery for the full parameter rules.

Identifying the returning user

The Redirect URL is a fixed value on the link (exact-match against the allow-list), and no user or session identifier is attached to the redirect. Determine "who came back" on your return page as follows:

• The returning browser is the very browser that opened the link. If the link was opened from a CTA on your service's page, your login session (cookies) is still there, so identifying the user by your own session on the return page is the primary method. If you delivered the link through a channel with no login session (SMS, QR), require a sign-in on the return page or look the result up by externalPetId in the Console.
• Which pet the result belongs to is defined by the externalPetId you attached when handing out the link, and the Console's result views show that ID too.
• Dynamically appending per-user parameters to the Redirect URL is not supported. If you need reliable per-session correlation, use Server Integration — the session id you stored at issuance matches the result's sessionId/externalPetId.

Register links: the redirect is the result

A Register link's completion redirect carries no petify_code. petify_status=completed itself means the registration succeeded — there is nothing extra to fetch. Details of the registered pet are available in the Console.

Verify and Identify links: a display-only code

A Verify or Identify link's completion redirect carries a one-time display code (petify_code=hrc_...). Your return page's frontend can read it without credentials to show the user their result:

// Your return page (frontend)
const params = new URLSearchParams(window.location.search);
if (params.get("petify_status") === "completed") {
  const code = params.get("petify_code");
  const response = await fetch(
    `https://api.petify.petnow.io/hosted/v1/results/${code}:display`
  );
  const { data } = await response.json();
  // Verify:   { action: "VERIFY", outcome: "MATCH", isVerified: true, completedAt: "..." }
  // Identify: { action: "IDENTIFY", outcome: "MATCH", isVerified: null, completedAt: "..." }
}

• The code stays valid for about 10 minutes after the session completes, and can be re-read within that window — a page refresh on your result screen keeps working.
• The response carries only a coarse result (outcome, plus isVerified for Verify). Scores, candidate lists, and pet IDs are never exposed.

In the Console

The Console is the only place that shows a completed session's full result (including the Petify Pet ID and Identify candidates with scores). Each Register link's progress (cumulative registrations / cap) is also visible on the link detail view.

Server-side reads (optional)

If you have an API key, sessions created from links can also be read server-side via GET /v2/hosted-sessions/{id}. Session IDs are shown in the Console's session views. See the session polling section of Server Integration for details.

Next steps

• Server Integration - Issue sessions from your server and receive trusted results
• Redirect URLs & Result Delivery - Allow-list management and redirect parameters