Connection
Connecting a vet's WisePaws account to your product. Runs once per vet, not per consult. Setting up a practice, joining an existing one and subscribing all happen on WisePaws, and none of it touches your product.
Send a vet to WisePaws to connect their account
GEThttps://app.wisepaws.vet/connect/{partner}
A browser navigation, not an API call. Send the vet here in a full-page redirect or a popup.
They sign in or sign up, sort out their practice, and confirm the connection. We then return them to your redirect_uri with a single-use code and your unmodified state.
You never send us an identifier for the vet. Storing the token you get from /v1/connections/exchange against your own user record is the entire mapping between your account and ours.
No connection token. This operation is not authenticated with one.
Parameters
partnerstringrequired
Your partner slug, issued by WisePaws when your integration is registered.
Example: "acme"
redirect_uristring (uri)required
Where to return the vet after they approve or cancel. Must exactly match a URI registered with us in advance; unregistered values are rejected rather than followed.
Example: "https://acme.example.com/integrations/wisepaws/done"
statestringrequired
Opaque value returned to you untouched. Use it to protect against CSRF and to recognise which of your users began the flow. We never read it.
Example: "f0b1c9e4a7"
email_hintstring (email)
Prefills the email field so the vet types less during sign-up. Treated as a hint only, never used to identify or authenticate anyone, so a wrong or forged value is harmless.
Example: "vet@example.com"
Responses
302
Redirect back to your redirect_uri. On approval the query carries code and state. On cancellation it carries error=access_denied and state.
400
Unknown partner slug, a disabled integration, or a redirect_uri that is not registered. Not redirected; shown to the vet.
Exchange the code for a connection token
POST/v1/connections/exchange
Server to server, within 60 seconds of receiving the code. Single use.
Keeping this a separate step means the long-lived token never appears in a browser URL, referrer header or your web access logs.
Your client secret is required. The code reaches you through the vet's browser, so it is readable in history, by extensions, and in your own access logs: the secret is what makes reading it insufficient. It is issued when your integration is registered and must never leave your backend.
No connection token. This operation is not authenticated with one.
Request body
application/json
client_idstringrequired
Your partner slug, the same one that appears in the connect URL.
Example: "acme"
client_secretstringrequired
Issued when your integration is registered. Backend only: a secret that reaches a browser is not a secret.
Example: "cs_live_4Kq9..."
codestringrequired
The single-use code from the connect redirect.
Example: "ac_7f3d2b91c0e4"
Responses
Every failure below returns the Error shape.
200
Connected.
Returns ConnectionGrant.
400Bad Request
The request was rejected. Do not retry unchanged.
401
The client_id and client_secret pair was not recognised. The two are never distinguished: a caller learns only that the pair is wrong.
json
{
"error": "That client_id and client_secret pair was not recognised.",
"code": "invalid_client"
}410
The code has expired or already been used. Restart the connect flow.
json
{
"error": "That connection code has expired. Ask the vet to connect again.",
"code": "invalid_code"
}429Rate Limited
On the note endpoints the ceiling is per connection, and submitting a recording is held far tighter than polling, which the contract asks you to do every 3 seconds. On /v1/connections/exchange, which has no connection yet, it is per source address. A platform-wide backstop sits above both; it is sized so that normal traffic never reaches it. Back off and respect Retry-After.
502Server Error
Something failed on our side before your request could be judged. Retry shortly: nothing was consumed, and no note was created.
Who is connected, and can they generate notes
GET/v1/connection
Read this when your consultation screen loads, and hide or disable recording when status is inactive.
Discovering a subscription problem at submit time means the consult is already over and the audio already captured: a failure the vet cannot recover from. The value changes rarely enough to cache for the session.
Responses
Every failure below returns the Error shape.
200
The connection behind the presented token.
Returns Connection.
401Unauthorized
The token is missing, malformed, or no longer valid. connection_revoked means the vet disconnected or left the practice, so clear the stored token and send them through the connect flow again.
partner_disabled is different and reconnecting will not fix it: your integration itself is switched off, and every token you hold stops at once. Stop retrying and contact us.
502Server Error
Something failed on our side before your request could be judged. Retry shortly: nothing was consumed, and no note was created.