{"openapi":"3.1.0","info":{"title":"Provkeep API","version":"2","description":"What each US state and federal agency published about a product, for an order. Answers quote the rule with its source and date. Provkeep does not say whether an order is lawful and never holds one on its own failure."},"servers":[{"url":"https://api.provkeep.com/v2","description":"live, pk_live_ keys"},{"url":"https://sandbox.provkeep.com/v2","description":"sandbox, pk_test_ keys"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Line":{"type":"object","required":["peptide"],"properties":{"line_id":{"type":"string","description":"Your own line reference. Defaults to the line's position."},"peptide":{"type":"string","description":"The product, by any name or alias we hold. Required."},"name":{"type":"string","description":"The product name as you sell it, kept for your record."},"dosage_form":{"type":"string","description":"For example injectable, oral, nasal, topical."},"route":{"type":"string","description":"Route of administration, when it matters to a rule."},"blend":{"type":"boolean","description":"true when the line is a blend of more than one product."},"ingredients":{"type":"array","items":{"type":"string"},"description":"A blend's or stack's ingredients, each read on its own. At most 20."},"lot_number":{"type":"string","description":"The lot it ships from, for your record. A value shaped like personal information is dropped."},"device_supplied":{"type":"boolean","description":"true when a device such as a pen or syringe ships with it. Kept for your record."},"quantity":{"type":"number","description":"How many units. A positive number."}},"additionalProperties":true},"Order":{"type":"object","required":["lines","patient_state"],"properties":{"code":{"type":"string","description":"Your own order or prescription reference. A value shaped like personal information (an email address, a date, a Social Security number pattern, or a phone length number) is replaced by the check ID and not kept."},"event":{"type":"string","description":"What happened: order_created, prescription_signed, order_shipped, order_updated. Anything else is read as order_created.","enum":["order_created","prescription_signed","order_shipped","order_updated"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/Line"},"description":"The products on the order, at most 50. Each line is described below."},"patient_state":{"type":"string","description":"The two letter US state the order goes to. Only the state is read: there is no field for a city, ZIP code or address, and an unknown field is dropped without its value being kept."},"prescriber_state":{"type":"string","description":"The two letter state the prescriber is in, when it differs."},"pharmacy_state":{"type":"string","description":"The two letter state the pharmacy ships from."},"pharmacy_type":{"type":"string","description":"How the product is dispensed, in your own words (for example 503A or 503B). Read against a vocabulary; an unknown value falls back to the account's setting."},"consult_type":{"type":"string","description":"How the patient was seen: in_person, video, phone, async_questionnaire. Used to match rules limited to one kind of consult.","enum":["in_person","video","phone","async_questionnaire"]},"purpose":{"type":"string","description":"What the product is for, as a code: treatment, weight_management, athletic_performance, wellness, other. Never free text.","enum":["treatment","weight_management","athletic_performance","wellness","other"]},"preview":{"type":"boolean","description":"true checks the order without recording it."},"placed_at":{"type":"string","format":"date-time","description":"When the order was placed. Refused if more than a day ahead."},"consent":{"type":"object","description":"The consent shown at checkout: the wording or its sha256 as terms_sha256, terms_version, gate (block, observe, record_only), shown_at and accepted_at. Never the customer."}},"additionalProperties":true,"description":"Unknown fields are dropped and counted, and their values are not kept."},"Answer":{"type":"object","description":"Always present: transaction_id, code, environment, checked, recorded, hold_requested, summary, ruleset_version, answered_at, lines, messages, fields_dropped, notice. When checked is false, reason_code and why say why.","properties":{"transaction_id":{"type":"string"},"code":{"type":"string"},"environment":{"type":"string","enum":["live","sandbox"]},"checked":{"type":"boolean"},"recorded":{"type":"boolean"},"hold_requested":{"type":"boolean"},"reason_code":{"type":"string","enum":["no_api_key","unknown_api_key","wrong_environment","account_not_linked","rate_limited","body_not_json","not_on_this_plan","account_inactive","service_unavailable"]},"why":{"type":"string"},"ruleset_version":{"type":["string","null"]},"answered_at":{"type":"string","format":"date-time"},"lines":{"type":"array","items":{"type":"object"}},"messages":{"type":"array","items":{"type":"object"}},"fields_dropped":{"type":"integer"},"notice":{"type":"string"}}}}},"paths":{"/checks":{"post":{"summary":"Check an order. Always answers 200 with an answer, including when we could not check it, so a checkout never waits on us. Records the order unless preview is true.","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}},{"name":"Provkeep-Account","in":"header","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"responses":{"200":{"description":"An answer, checked or not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"401":{"description":"No key, an unknown key, or the wrong environment."},"422":{"description":"Idempotency-Key reused with a different body."}}}},"/checks/{id}":{"get":{"summary":"The answer a check gave, by its check ID, for this account only.","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The answer."},"404":{"description":"No check with that ID on this account."}}}},"/orders/{reference}/events":{"post":{"summary":"What happened after the check: shipped (with a lot per line), refunded, cancelled or edited, named by your own order number. Appended, never written over the answer.","security":[{"bearer":[]}],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Kept."},"400":{"description":"No reference, or the body was not JSON."}}}},"/rulesets/current":{"get":{"summary":"The version and build time of the rules every answer is read from today.","responses":{"200":{"description":"version and built_at."}}}},"/status":{"get":{"summary":"Whether the service can reach its data, how old the rules are, and how many records are waiting to be written.","responses":{"200":{"description":"service ok or degraded."}}}}},"x-rate-limit":"200 checks a second per key, bursts up to 500.","x-change-policy":"https://provkeep.com/developers/api#changes"}