{"openapi":"3.1.0","info":{"title":"VeriGiving API","version":"1.0.0","description":"Start and manage contribution pages for families from your own software. Amounts are Canadian dollars as numbers. Contributions of 1000 or more include an identity check on the page, as Canadian law requires. Keys starting vg_test_ create test pages that never email anyone and never take money."},"servers":[{"url":"https://verigiving.com/api/v1"}],"security":[{"bearer":[]}],"paths":{"/business":{"get":{"summary":"The business this key belongs to","responses":{"200":{"description":"The business","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages":{"get":{"summary":"List pages, newest first","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["collecting","settled","closed"]}},{"name":"client_reference","in":"query","description":"Only pages for this client id from your own CRM or case system","schema":{"type":"string","maxLength":120}},{"name":"reference","in":"query","description":"Only pages whose invoice carries this reference","schema":{"type":"string","maxLength":80}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"starting_after","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A list of pages","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Page"}},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Start a page for a family","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":120},"description":"Unique per file in your system; a retry returns the original page."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","family_name","amount"],"properties":{"title":{"type":"string","maxLength":160},"family_name":{"type":"string","maxLength":120},"amount":{"type":"number","minimum":100,"maximum":500000},"family_email":{"type":"string","format":"email"},"notify_family":{"type":"boolean","default":true},"story":{"type":"string","maxLength":5000},"reference":{"type":"string","maxLength":80},"client_reference":{"type":"string","maxLength":120,"description":"The id of this client in your own CRM or case system"},"visibility":{"type":"string","enum":["link_only","public"],"default":"link_only"}}}}}},"responses":{"200":{"description":"Replayed idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{id}":{"get":{"summary":"Retrieve a page","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Revise the invoice, edit the text, change visibility, close or reopen","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_total":{"type":"number","minimum":100,"maximum":500000},"note":{"type":"string","maxLength":200},"status":{"type":"string","enum":["closed","collecting","cancelled"]},"visibility":{"type":"string","enum":["link_only","public"]},"title":{"type":"string"},"story":{"type":"string"},"family_email":{"type":"string","format":"email"},"client_reference":{"type":"string","maxLength":120},"confirm_refunds":{"type":"boolean","description":"Required when invoice_total is below what has been collected; the difference is returned to contributors pro rata"}}}}}},"responses":{"200":{"description":"The updated page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{id}/contributions":{"get":{"summary":"List contributions to a page","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"A list of contributions","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contribution"}},"has_more":{"type":"boolean"}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"event":{"post":{"summary":"Sent to the endpoints you register in the dashboard","description":"Signed with VeriGiving-Signature: t=<unix seconds>,v1=<hex HMAC SHA256 of '<t>.<raw body>' using your endpoint secret>.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["contribution.succeeded","contribution.refunded","page.settled","page.closed","page.reopened"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Any 2xx response acknowledges the event"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"vg_sk_... (live) or vg_test_... (test)"}},"schemas":{"Page":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"page"},"slug":{"type":"string"},"title":{"type":"string"},"family_name":{"type":"string"},"family_email":{"type":["string","null"]},"client_reference":{"type":["string","null"]},"story":{"type":["string","null"]},"status":{"type":"string","enum":["collecting","settled","closed"]},"visibility":{"type":"string","enum":["link_only","public"]},"created_via":{"type":"string","enum":["web","api"]},"invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"total":{"type":"number"},"currency":{"type":"string"},"reference":{"type":["string","null"]},"document_url":{"type":["string","null"]},"confirmed_at":{"type":["string","null"],"format":"date-time"}}},"contributed_total":{"type":"number"},"remaining":{"type":"number"},"contributor_count":{"type":"integer"},"url":{"type":"string","format":"uri"},"own_domain_url":{"type":["string","null"],"format":"uri"},"qr_url":{"type":"string","format":"uri"},"test":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Contribution":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"contribution"},"amount":{"type":"number"},"currency":{"type":"string"},"contributor_name":{"type":["string","null"]},"note":{"type":["string","null"]},"status":{"type":"string","enum":["succeeded","refunded"]},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request","authentication_error","not_found","invalid_state","rate_limit_error","api_error"]},"message":{"type":"string"},"param":{"type":"string"}}}}}}}}