WisePaws Partner API

Quickstart ​

The shortest path from nothing to a note in your product. Four calls, in order.

You need a client_id (your slug), a client_secret, and at least one registered redirect URI. Ask us and we will issue them.

1. Connect a vet, once ​

Send the vet to WisePaws in a full-page browser navigation or a popup, not an iframe. They sign in, pick the practice this connection is for, and approve.

https://app.wisepaws.vet/connect/acme
  ?redirect_uri=https://acme.example.com/integrations/wisepaws/done
  &state=<opaque value you generate>

redirect_uri must match one you registered with us, exactly. We come back to it with a single-use code and your state unchanged. Check the state before you use the code.

Exchange the code from your backend, within 60 seconds:

bash
curl -X POST https://api.wisepaws.vet/v1/connections/exchange \
  -H 'Content-Type: application/json' \
  -d '{
        "client_id": "acme",
        "client_secret": "<your secret>",
        "code": "<the code from the redirect>"
      }'

You get a connection_token. Store it against that vet and that practice, and read how an integration fits together before you decide where. Every call from here sends Authorization: Bearer <connection_token>.

See exchangeConnectionCode for the full contract.

2. Submit a consult ​

One complete recording, one note. Relay it from your backend rather than from the vet's browser.

bash
curl -X POST https://api.wisepaws.vet/v1/notes \
  -H 'Authorization: Bearer <connection_token>' \
  -H 'Idempotency-Key: 7c1e0a44-9b2f-4de6-8a31-5f0c2d9e7b18' \
  -F 'audio=@consult.ogg;type=audio/ogg' \
  -F 'language=en' \
  -F 'note_format=soap' \
  -F 'pet_name=Willow' \
  -F 'pet_type=rabbit' \
  -F 'external_ref=acme_consult_44192' \
  -F 'captured_seconds=276.4'

Three things are worth getting right here.

Store the Idempotency-Key before you call us. It is also the note's address, so holding it means you can poll even if our response never arrives. This is the single most important line in the integration and it has its own section.

Send Opus if you can. It is the smallest of the accepted formats, and the one where we read duration from the container rather than computing it.

Send captured_seconds. It is how we tell a short consult from a truncated one. Without it we cannot warn the vet that part of the consult was lost in transit.

Every accepted field is listed under createNote.

3. Poll until it is ready ​

bash
curl https://api.wisepaws.vet/v1/notes/7c1e0a44-9b2f-4de6-8a31-5f0c2d9e7b18 \
  -H 'Authorization: Bearer <connection_token>'

Poll every 3 seconds. Most consults are ready within 90 seconds; a long one can take several minutes. Treat anything past 5 minutes as failed and tell the vet, rather than polling for ever.

On success you get the note as a list of sections. Map your destination fields on each section's key, never on its position in the array. The order is stable today and is not part of the contract, so a position-based mapping is a bug waiting for the first time we change it.

When the status comes back failed, do not stop here: when a consult fails is the guide that matters most, because a consult cannot be re-recorded.

4. Tell us what the vet did ​

bash
curl -X POST https://api.wisepaws.vet/v1/notes/7c1e0a44-9b2f-4de6-8a31-5f0c2d9e7b18/outcome \
  -H 'Authorization: Bearer <connection_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "outcome": "filed",
        "sections": [
          { "key": "plan", "content": "Analgesia and prokinetic support..." }
        ]
      }'

Optional, and the only signal we ever get about whether a note was actually usable. Sending the filed text lets us report back to the practice how much of each section their vets keep, and it is what improves the notes they see over time. A discard needs no body and is just as useful.

It is idempotent, so a vet who reopens the note and edits again can be reported again. See recordNoteOutcome.

Next ​