Create an action · Vene Docs

Creates an action and starts work on it at once.

POST/v1/actions

Headers

Idempotency-KeystringRequired
A unique key per action. A retry with the same key returns the first action. Up to 255 characters.

Parameters

typeenumRequired
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.
inputobjectRequired
Its fields depend on type. See the action types.
patientobjectRequired
Who the prescription is for.
refstringRequired
Your ID for the patient. Vene uses it to match callbacks. Up to 255 characters.
first_namestringRequired
As the place has it on file. Up to 120 characters.
last_namestringRequired
As the place has it on file. Up to 120 characters.
date_of_birthdateRequired
Places check it with the name.
pharmacyobjectRequired
Where it was sent.
namestringRequired
Such as CVS Pharmacy. Up to 255 characters.
addressobjectRequired
The exact store.
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
npistring
The pharmacy NPI. 10 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
prescriptionobjectRequired
What to ask about.
drug_namestringRequired
Such as lisinopril. Up to 255 characters.
strengthstring
Such as 10 mg. Up to 64 characters.
formstring
Such as tablet. Up to 64 characters.
quantityinteger
Units in the fill. 1 to 10,000.
rx_numberstring
The pharmacy's number for it. Makes every call faster. Up to 64 characters.
prescriberobject
Who wrote it.
first_namestringRequired
The clinician's first name. Up to 120 characters.
last_namestringRequired
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.
addressobjectRequired
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
include_cash_priceboolean
Also ask the cash price.
from_pharmacyobjectRequired
Where it is now.
namestringRequired
Such as CVS Pharmacy. Up to 255 characters.
addressobjectRequired
The exact store.
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
npistring
The pharmacy NPI. 10 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
to_pharmacyobjectRequired
Where it should go. Vene calls this one.
namestringRequired
Such as CVS Pharmacy. Up to 255 characters.
addressobjectRequired
The exact store.
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
npistring
The pharmacy NPI. 10 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
insuranceobject
The receiving pharmacy usually asks for it.
payer_namestringRequired
Up to 255 characters.
plan_namestring
Up to 255 characters.
member_idstringRequired
From the card. Up to 64 characters.
group_numberstring
From the card. Up to 64 characters.
rx_binstring
Pharmacy BIN from the card. Up to 32 characters.
rx_pcnstring
Pharmacy PCN from the card. Up to 32 characters.
rx_groupstring
Pharmacy group from the card. Up to 64 characters.
drugobjectRequired
What to look for.
drug_namestringRequired
Up to 255 characters.
strengthstringRequired
Up to 64 characters.
formstring
Up to 64 characters.
quantityintegerRequired
How much the patient needs. 1 to 10,000.
pharmaciesarray of objectsRequired
Called in this order. 1 to 10 items.
namestringRequired
Such as CVS Pharmacy. Up to 255 characters.
addressobjectRequired
The exact store.
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
npistring
The pharmacy NPI. 10 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
provideranyRequired
Whose openings to ask about.
patient_relationshipenumRequired
New or established patient.
Possible values
newHas not seen this provider or practice in three years.
establishedHas seen them in the last three years.
reasonstringRequired
Openings differ by visit type.
insurance_planobject
Ask whether the office takes it.
payer_namestringRequired
Such as Aetna. Up to 255 characters.
plan_namestring
Such as Aetna Choice POS II. Up to 255 characters.
referralobject
Send it when the office needs one.
referring_providerobjectRequired
first_namestringRequired
The clinician's first name. Up to 120 characters.
last_namestringRequired
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.
addressobjectRequired
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
phonestring
A hint. Vene checks the number before it dials. E.164 phone number.
referral_numberstring
Up to 64 characters.
preferred_windowsarray of objectsRequired
Times the patient can make. 1 to 10 items.
starttimestampRequired
When the window opens.
endtimestampRequired
When it closes. After start.
appointmentobjectRequired
The current appointment.
starts_attimestampRequired
duration_minutesinteger
1 to 1,440.
provideranyRequired
Needs npi or practice, so Vene can find the office.
locationobject
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
confirmation_numberstring
Up to 64 characters.
arrival_instructionsstring
Up to 2,000 characters.
max_feeobject
The most the patient will pay to change it. Omit it and Vene goes ahead and reports any fee.
amount_centsintegerRequired
Whole cents.
currencyenumRequired
Always USD.
Possible values
USDUS dollars.

Returns

The action, status queued.

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.
409idempotency_conflict
The key was used with a different body.
429rate_limited
Over a limit. Wait for Retry-After.
500internal_error
A Vene fault.

curl -X POST https://api.venehealth.com/v1/actions \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "find_availability",
  "input": {
    "provider": {
      "first_name": "Maya",
      "last_name": "Chen",
      "credential": "MD",
      "npi": "1992837465",
      "specialty": "cardiology"
    },
    "patient_relationship": "new",
    "reason": "Follow-up after a hospital stay for atrial fibrillation",
    "insurance_plan": {
      "payer_name": "Aetna",
      "plan_name": "Aetna Choice POS II"
    }
  }
}
JSON

const response = await fetch('https://api.venehealth.com/v1/actions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api_key>',
    'Idempotency-Key': '<idempotency_key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "find_availability",
    "input": {
      "provider": {
        "first_name": "Maya",
        "last_name": "Chen",
        "credential": "MD",
        "npi": "1992837465",
        "specialty": "cardiology"
      },
      "patient_relationship": "new",
      "reason": "Follow-up after a hospital stay for atrial fibrillation",
      "insurance_plan": {
        "payer_name": "Aetna",
        "plan_name": "Aetna Choice POS II"
      }
    }
  }),
})
const result = await response.json()

{
  "id": "<action_id>",
  "type": "find_availability",
  "status": "queued",
  "input": {
    "provider": {
      "first_name": "Maya",
      "last_name": "Chen",
      "credential": "MD",
      "npi": "1992837465",
      "specialty": "cardiology"
    },
    "patient_relationship": "new",
    "reason": "Follow-up after a hospital stay for atrial fibrillation",
    "insurance_plan": {
      "payer_name": "Aetna",
      "plan_name": "Aetna Choice POS II"
    }
  },
  "questions": [],
  "result": null,
  "trail": [],
  "created_at": "2026-11-02T17:00:00.000Z",
  "updated_at": "2026-11-02T17:00:00.000Z",
  "ended_at": null
}

{
  "id": "<action_id>",
  "type": "find_availability",
  "status": "in_progress",
  "input": {
    "provider": {
      "first_name": "Maya",
      "last_name": "Chen",
      "credential": "MD",
      "npi": "1992837465",
      "specialty": "cardiology"
    },
    "patient_relationship": "new",
    "reason": "Follow-up after a hospital stay for atrial fibrillation",
    "insurance_plan": {
      "payer_name": "Aetna",
      "plan_name": "Aetna Choice POS II"
    }
  },
  "questions": [],
  "result": null,
  "trail": [
    {
      "id": "<call_id>",
      "call_type": "ask_provider_availability",
      "place": {
        "name": "Oakland Heart Center",
        "address": {
          "line1": "3000 Telegraph Ave",
          "city": "Oakland",
          "state": "CA",
          "postal_code": "94609"
        },
        "phone": "+15105550147"
      },
      "started_at": "2026-11-02T17:00:15.000Z",
      "ended_at": null,
      "ended_reason": null
    }
  ],
  "created_at": "2026-11-02T17:00:00.000Z",
  "updated_at": "2026-11-02T17:00:20.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": "idempotency_conflict",
    "message": "This Idempotency-Key was used with a different request body"
  }
}

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

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