{ "openapi": "3.0.0", "paths": { "/v1/partner/sessions": { "post": { "description": "Finds or creates the sale for partner_reference as the key's user, applies prefill to the parts nobody has started, and returns a session token for Before.open(). The same reference always reopens the same sale with a new token.", "operationId": "createSession", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionDto" } } } }, "responses": { "201": { "description": "A new session token on the sale this reference names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "400": { "description": "The body failed validation; `errors` lists each path.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "403": { "description": "The key may not call this route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "409": { "description": "Conflicts with the current state; see `type`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "422": { "description": "Valid shape, but cannot be applied; see `type` and `errors`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "429": { "description": "Rate limited; retry after a pause.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Open an embedded sale session", "tags": [ "partner-public" ] } }, "/v1/partner/sales/{id}": { "get": { "description": "A sale opened through POST /v1/partner/sessions, in the calling key's mode, and visible to the key's user. policy is null until the carrier issues it.", "operationId": "getSale", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The sale_id POST /v1/partner/sessions returned.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The sale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleResponseDto" } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "403": { "description": "The key may not call this route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "404": { "description": "No such sale for this key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "409": { "description": "Conflicts with the current state; see `type`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } }, "429": { "description": "Rate limited; retry after a pause.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read a sale", "tags": [ "partner-public" ] } } }, "info": { "title": "Before Partner API", "description": "Open embedded sale sessions and read their outcome. Guides: https://docs.before.com", "version": "1.0", "contact": {} }, "tags": [ { "name": "partner-public", "description": "" } ], "servers": [ { "url": "https://api.before.com" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "API key", "type": "http", "description": "Your API key: `bk_live_…` for real sales, `bk_test_…` for the sandbox." } }, "schemas": { "ProblemDto": { "type": "object", "properties": { "type": { "description": "https://before.com/problems/; branch on the code, e.g. location-required.", "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "description": "Human-readable; do not parse.", "type": "string" }, "instance": { "type": "string" }, "correlation_id": { "description": "Quote it when you contact Before support.", "type": "string" }, "errors": { "description": "Per-field violations, or the choices for location-required and location-inactive.", "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "type", "title", "status" ] }, "CreateSessionDto": { "type": "object", "properties": { "partner_reference": { "description": "Your id for this sale. The same reference reopens the same sale.", "type": "string", "minLength": 1, "maxLength": 128 }, "location_id": { "description": "Required when the tenant has more than one active location.", "type": "string", "format": "uuid" }, "prefill": { "type": "object", "properties": { "insured": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "middle_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "date_of_birth": { "type": "string" }, "sex": { "type": "string", "enum": [ "female", "male" ] }, "phone": { "description": "Any common US format; normalized to 10 digits.", "type": "string", "minLength": 10, "maxLength": 25 }, "email": { "type": "string", "format": "email" }, "address": { "type": "object", "properties": { "street_1": { "type": "string", "minLength": 1, "maxLength": 200 }, "street_2": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[\\p{L}\\p{M}'\\u2019 .-]+$" }, "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "postal_code": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, "required": [ "street_1", "city", "state", "postal_code" ] }, "ssn_last4": { "type": "string", "pattern": "^\\d{4}$" } }, "required": [ "first_name", "last_name" ] }, "owner": { "oneOf": [ { "type": "object", "properties": { "same_as_insured": { "type": "boolean" } }, "required": [ "same_as_insured" ] }, { "type": "object", "properties": { "same_as_insured": { "type": "boolean" }, "person": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "middle_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "date_of_birth": { "type": "string" }, "sex": { "type": "string", "enum": [ "female", "male" ] }, "phone": { "description": "Any common US format; normalized to 10 digits.", "type": "string", "minLength": 10, "maxLength": 25 }, "email": { "type": "string", "format": "email" }, "address": { "type": "object", "properties": { "street_1": { "type": "string", "minLength": 1, "maxLength": 200 }, "street_2": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[\\p{L}\\p{M}'\\u2019 .-]+$" }, "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "postal_code": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, "required": [ "street_1", "city", "state", "postal_code" ] }, "ssn_last4": { "type": "string", "pattern": "^\\d{4}$" } }, "required": [ "first_name", "last_name" ] }, "relationship": { "type": "string", "enum": [ "spouse", "son", "daughter", "father", "mother", "brother", "sister", "grandson", "granddaughter", "grandfather", "grandmother", "aunt", "uncle", "partner", "trust", "estate", "power_of_attorney", "other" ] } }, "required": [ "same_as_insured", "person", "relationship" ] } ] }, "beneficiaries": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "last_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "middle_name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\p{L}[\\p{L}\\p{M}'\\u2019 .-]*$" }, "relationship": { "type": "string", "enum": [ "assignee", "spouse", "son", "daughter", "father", "mother", "brother", "sister", "grandson", "granddaughter", "grandfather", "grandmother", "aunt", "uncle", "nephew", "niece", "cousin", "friend", "church", "partner", "trustee", "estate", "policy_owner", "other" ] }, "percentage": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false }, "phone": { "description": "Any common US format; normalized to 10 digits.", "type": "string", "minLength": 10, "maxLength": 25 }, "address": { "type": "object", "properties": { "street_1": { "type": "string", "minLength": 1, "maxLength": 200 }, "street_2": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[\\p{L}\\p{M}'\\u2019 .-]+$" }, "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "postal_code": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" } }, "required": [ "street_1", "city", "state", "postal_code" ] } }, "required": [ "first_name", "last_name", "relationship", "percentage" ] } } } } }, "required": [ "partner_reference" ] }, "SessionResponseDto": { "type": "object", "properties": { "session_token": { "description": "Pass to Before.open(). Valid until expires_at; shown once.", "type": "string" }, "sale_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "skipped_prefill": { "description": "Prefill keys not applied because the user already started that part of the sale.", "type": "array", "items": { "type": "string", "enum": [ "insured", "owner", "beneficiaries" ] } }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "agent-unlicensed" ] } } }, "required": [ "session_token", "sale_id", "expires_at", "skipped_prefill", "warnings" ] }, "SaleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partner_reference": { "type": "string" }, "status": { "type": "string", "enum": [ "in_process", "ready_for_review", "out_for_signature", "partially_signed", "signed", "submitted", "in_underwriting_review", "pended_info_needed", "approved", "issued", "declined", "closed_lost" ] }, "mode": { "description": "`live` sells real policies; `test` creates practice sales (the sandbox).", "type": "string", "enum": [ "live", "test" ] }, "policy": { "description": "Present once the carrier issues the policy.", "type": "object", "properties": { "number": { "type": "string" }, "carrier": { "description": "Carrier name.", "type": "string" }, "premium": { "description": "Modal premium, an exact decimal string.", "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,4})?$" } }, "required": [ "number", "carrier", "premium" ], "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "partner_reference", "status", "mode", "policy", "updated_at" ] } } } }