Answer questions · Vene Docs

Answers one or more open questions in one request.

POST/v1/actions/{action_id}/answer

Path parameters

action_idstringRequired
Starts with act_.

Parameters

answersarray of objectsRequired
One per question. 1 to 20 items.
question_idstringRequired
The open question. Starts with q_.
answerobjectRequired
A value checked against the question's type, or unavailable.
valueanyRequired
unavailableenumRequired
Possible values
true
notestring
Up to 500 characters.

Returns

The action, its questions now answered.

actionobject
idstring
The action ID. Starts with act_.
typeenum
The action type.
Possible values
pharmacy_statusIs a prescription ready.
pharmacy_transferMove a prescription.
pharmacy_stock_checkWho has a drug in stock.
find_availabilityFind openings.
book_appointmentBook a visit.
reschedule_appointmentMove a visit.
cancel_appointmentCancel a visit.
statusenum
Where the action stands.
Possible values
queuedAccepted, not started.
in_progressLooking up numbers or on a call.
waiting_for_answerAsked you a question. Continues when you answer.
waiting_for_callbackWaiting to call again, or for a place to call back.
succeededThe place gave a definite answer.
failedNo definite answer. See failure_reason.
cancelledYou cancelled it.
inputobject
What you sent. Its fields depend on type; see the action types.
questionsarray of objects
Every question, oldest first.
questionstring
Up to 500 characters.
helpstring, nullable
call_idstring
Starts with call_.
typeenum
Possible values
inputFill one optional input field.
textFree text.
numberA number, within any limits.
booleanYes or no.
dateA date.
choiceOne of the offered options.
slotPick an offered opening, or send new windows.
pathstring
Up to 200 characters.
idstring
Starts with q_.
asked_attimestamp
answered_attimestamp, nullable
answerobject, nullable
valueany
unavailableenum
Possible values
true
notestring
max_lengthinteger
1 to 2,000.
integerboolean
minnumber
maxnumber
optionsarray of objects
idstring
labelstring
Up to 200 characters.
slotobject
starts_attimestamp
When the visit starts.
duration_minutesinteger
How long it runs. 1 to 1,440.
providerobject
Who the visit is with.
first_namestring
The clinician's first name. Up to 120 characters.
last_namestring
The clinician's last name. Up to 120 characters.
credentialstring
Such as MD or NP. Up to 32 characters.
npistring
The clinician's NPI. The surest way to find the office. 10 digits.
specialtystring
Such as cardiology. Up to 120 characters.
practiceobject
Where the patient is seen.
namestring
Such as Oakland Heart Center. Up to 255 characters.
addressobject
line1string
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystring
Up to 120 characters.
statestring
Such as CA. Two-letter state code.
postal_codestring
Five-digit ZIP code. 5 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
locationobject
Where. Always set in results.
line1string
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystring
Up to 120 characters.
statestring
Such as CA. Two-letter state code.
postal_codestring
Five-digit ZIP code. 5 digits.
held_untiltimestamp, nullable
multipleboolean
resultobject, nullable
Set when it ends. These fields are shared; the rest depend on type (action types).
summarystring
What happened, in a sentence or two. Up to 2,000 characters.
failure_reasonenum, nullable
Why it failed. Null unless failed.
Possible values
patient_authorization_requiredThe place needs the patient herself to authorize it.
place_would_not_helpThe place would not discuss it with Vene.
place_unreachableClosed, never answered, or no working number.
declined_by_youYou declined something the action needed.
fee_over_maxThe fee was over max_fee. The result names it.
internal_errorA Vene fault.
next_stepstring, nullable
What you could do next. Up to 1,000 characters.
trailarray of objects
Every call, oldest first.
idstring
The call ID. Starts with call_.
call_typeenum
Why Vene made the call.
Possible values
ask_pharmacy_fill_statusAsk a pharmacy about a fill.
ask_prescriber_to_resolve_holdAsk a prescriber's office to act on a hold.
ask_pharmacy_to_transfer_prescriptionAsk a pharmacy to pull a transfer.
ask_pharmacy_stockAsk a pharmacy about stock.
ask_provider_availabilityAsk an office about openings.
book_provider_appointmentBook with an office.
reschedule_provider_appointmentReschedule with an office.
cancel_provider_appointmentCancel with an office.
inbound_callbackA place called Vene back.
placeobject
Who was on the other end.
namestring
addressobject, nullable
line1string
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystring
Up to 120 characters.
statestring
Such as CA. Two-letter state code.
postal_codestring
Five-digit ZIP code. 5 digits.
phonestring
The number dialed, or the one that called in. E.164 phone number.
started_attimestamp, nullable
When it connected.
ended_attimestamp, nullable
When it ended.
ended_reasonenum, nullable
How it ended.
Possible values
completedThe call ran to its end.
voicemailIt reached voicemail.
no_answerNobody picked up.
busyThe line was busy.
they_hung_upThe place hung up.
queue_callbackA phone queue took Vene's number to call back.
long_holdVene hung up after about ten minutes on hold.
created_attimestamp
When you created it.
updated_attimestamp
When it last changed.
ended_attimestamp, nullable
When it ended.

Errors

400invalid_request
The body or query failed validation.
401unauthorized
The API key is missing, unknown, or revoked.
403forbidden
The key lacks the scope.
404not_found
No such action or call for this key.
409action_not_waiting
No question is open.
429rate_limited
Over a limit. Wait for Retry-After.
500internal_error
A Vene fault.

curl -X POST https://api.venehealth.com/v1/actions/<action_id>/answer \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "answers": [
    {
      "question_id": "<question_id>",
      "answer": {
        "value": "opt_1"
      }
    },
    {
      "question_id": "<question_id_2>",
      "answer": {
        "value": "Aetna Choice POS II"
      }
    }
  ]
}
JSON

const response = await fetch('https://api.venehealth.com/v1/actions/<action_id>/answer', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api_key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "answers": [
      {
        "question_id": "<question_id>",
        "answer": {
          "value": "opt_1"
        }
      },
      {
        "question_id": "<question_id_2>",
        "answer": {
          "value": "Aetna Choice POS II"
        }
      }
    ]
  }),
})
const result = await response.json()

{
  "id": "<action_id>",
  "type": "book_appointment",
  "status": "in_progress",
  "input": {
    "patient": {
      "ref": "pt_123",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1958-03-14"
    },
    "provider": {
      "first_name": "Maya",
      "last_name": "Chen",
      "credential": "MD",
      "npi": "1992837465"
    },
    "patient_relationship": "new",
    "reason": "Follow-up after a hospital stay for atrial fibrillation",
    "insurance": {
      "payer_name": "Aetna",
      "plan_name": "Aetna Choice POS II",
      "member_id": "W123456789"
    },
    "referral": {
      "referring_provider": {
        "first_name": "Sam",
        "last_name": "Okafor",
        "credential": "DO"
      },
      "referral_number": "REF-20431"
    },
    "preferred_windows": [
      {
        "start": "2026-11-09T08:00:00-08:00",
        "end": "2026-11-09T12:00:00-08:00"
      },
      {
        "start": "2026-11-11T13:00:00-08:00",
        "end": "2026-11-11T17:00:00-08:00"
      }
    ]
  },
  "questions": [
    {
      "id": "<question_id>",
      "call_id": "<call_id>",
      "question": "Nothing was open in the preferred windows. The office offered two other times.",
      "help": null,
      "asked_at": "2026-11-02T19:20:00.000Z",
      "answered_at": "2026-11-02T19:41:10.000Z",
      "answer": {
        "value": "opt_1"
      },
      "type": "slot",
      "options": [
        {
          "id": "opt_1",
          "slot": {
            "starts_at": "2026-11-10T09:30:00-08:00",
            "duration_minutes": 40,
            "provider": {
              "first_name": "Maya",
              "last_name": "Chen",
              "credential": "MD"
            },
            "location": {
              "line1": "3000 Telegraph Ave",
              "city": "Oakland",
              "state": "CA",
              "postal_code": "94609"
            }
          },
          "held_until": "2026-11-03T17:00:00-08:00"
        },
        {
          "id": "opt_2",
          "slot": {
            "starts_at": "2026-11-12T14:00:00-08:00",
            "provider": {
              "first_name": "Maya",
              "last_name": "Chen",
              "credential": "MD"
            }
          },
          "held_until": null
        }
      ]
    }
  ],
  "result": null,
  "trail": [
    {
      "id": "<call_id>",
      "call_type": "book_provider_appointment",
      "place": {
        "name": "Oakland Heart Center",
        "address": {
          "line1": "3000 Telegraph Ave",
          "city": "Oakland",
          "state": "CA",
          "postal_code": "94609"
        },
        "phone": "+15105550147"
      },
      "started_at": "2026-11-02T19:12:00.000Z",
      "ended_at": "2026-11-02T19:19:30.000Z",
      "ended_reason": "completed"
    }
  ],
  "created_at": "2026-11-02T19:11:40.000Z",
  "updated_at": "2026-11-02T19:41:10.000Z",
  "ended_at": null
}

{
  "error": {
    "code": "invalid_request",
    "message": "Expected a two-letter state code",
    "field": "input.pharmacy.address.state"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This key lacks access to this request"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Action not found"
  }
}

{
  "error": {
    "code": "action_not_waiting",
    "message": "The action is not waiting for an answer"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "The Vene API is not configured here"
  }
}